xfs_db(8)

📦
version 7.2.1 · 9 versions
, in arch rolling, nixpkgs unstable

okay bestie, meet xfs_db(8) from the System Manager's Manual — the XFS filesystem debugger that's about to explain itself. 🦋

✨ 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. No cap. 💅

✨ 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. iykyk 💜
  • -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. expert mode, bestie 💅
  • -V — Prints the version number and exits. 🦋

🧠 CONCEPTS 🧠

So like, xfs_db commands split into two classes, bestie. Most commands are for the navigation and display of data structures in the filesystem. Other commands are for scanning the filesystem in some way. Both are iconic in their own lane. 💖

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 — the chaos gremlin command 💀

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

okay so this one trashes randomly picked filesystem metadata blocks — like, it goes in and flips random bits inside the blocks it chose. no cap. bestie, this is only available in debugging versions of xfs_db, and its whole personality is "let's break stuff so we can test xfs_repair(8)" 🫶

  • -0 | -1 | -2 | -3 — these set the operating mode for blocktrash, and you can only pick one of them:
    • -0 — changed bits get cleared
    • -1 — changed bits get set
    • -2 — changed bits get inverted
    • -3 — changed bits get randomized ✨
  • -n — how many block-trashings to do. default is 1.
  • -o — the bit offset where the trashing starts in the block. if you put a + in front of the value, the trashing starts at a randomly chosen offset that's larger than the value you gave. default is to just randomly pick an offset anywhere in the block.
  • -s — a seed for the random processing 🌱
  • -t — the type of blocks to select for trashing. you can give multiple -t options. if you give no -t options at all, then all metadata types can be trashed.
  • -x — the minimum size of the bit range to trash. default value is 1.
  • -y — the maximum size of the bit range to trash. default value is 1024.
  • -z — trashes the block at the top of the stack. if you use this option, you do not need to run blockget first.

🧮 blockuse

blockuse [-n] [-c count]

prints usage info for the current filesystem block(s). for every block it prints the type and, if there is one, the inode. very "who is this block and why are they here" energy 👑

  • -c — a count of blocks to process. default is 1 (so, just the current block).
  • -n — print file names. heads up: the earlier blockget command must also have been given the -n option for this to work.

🗺️ bmap

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

shows the block map for the current inode 💅 you can narrow the map display down to just part of the file using the block and len arguments. if you give block but leave out len, then len is assumed to be 1.

the -a and -d options pick the attribute or data area of the inode. if you give neither, both areas get shown. inclusive queen 🌸

🎈 bmapinflate — expert mode only, proceed with caution 😭

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.

⚠️ bestie this command leaves at least the refcount btree and the inode inconsistent. you must run xfs_repair afterwards. like, that's not optional. periodt.
  • -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, then exit without changing anything. the "look but don't touch" option, iconic 🙈
  • -n — create this many copies of the first mapping.

🌳 btdump

btdump [-a] [-i]

if the cursor points to a btree node, it dumps the btree from that block downward ⬇️ if instead the cursor points to an inode, it dumps the data fork block mapping btree if there is one. and if the cursor points to a directory or extended attribute btree node, it dumps that. by default, only records stored in the btree get dumped.

  • -a — if the cursor points at an inode, dump the extended attribute block mapping btree, if it's present.
  • -i — dump all keys and pointers in intermediate btree nodes, plus all records in leaf btree nodes. the full tea ☕

📏 btheight

btheight [-b blksz] [-n recs] [-w max|min|absmax|avg] btree types...

for a given number of btree records and a btree type, this reports the number of records and blocks for each level of the btree, plus the total number of blocks. the btree type has to come after the options, okay?

you can also hand it a raw btree geometry 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 — override the btree block size. default is the filesystem block size.
  • -n — specify the number of records to store. this argument is required. no skipping it bestie.
  • -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

convert type number [type number] ... type

converts from one address form to another. the known types, with their 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, so don't get creative 🙃 the compound form (with more than three arguments) is useful for conversions such as convert agno ag agbno agb fsblock.

✅ crc

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. every version of the 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

daddr [-r] [d]

sets the current address to the daddr (512 byte block) given by d. if you don't give a value for d, the current address is printed, expressed as a daddr. the type gets 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

dblock filoff

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

🐛 debug

debug [flagbits]

sets debug option bits. these are used for debugging xfs_db itself. if you don't give a value for flagbits, it prints the current debug option bits. heads up: these are for the use of the implementor, so it's giving "you had to be there" 🫠

👥 dquot

dquot [-g|-p|-u] id

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

🪣 dump_iunlinked

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

dumps 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. the tl;dr setting 💅
  • -v — print resource usage of each file on the unlinked lists.

📢 echo

echo [arg] ...

echoes the arguments to the output. that's it. that's the command. lowkey iconic ✨

⏩ f

see the forward command.

⏩ forward

moves forward to the next entry in the position ring 🔄

🧩 frag

frag [-adflqRrv]

gets file fragmentation data 📊 this prints info about fragmentation of file data in the filesystem (as opposed to fragmentation of freespace — for that, see the freesp command). every file in the filesystem gets examined to see how far from ideal its extent mappings are, and then 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 get examined. if you give no options, then all are assumed set — otherwise just the ones you gave 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

freesp [-bcds] [-A alignment] [-a ag] ... [-e i] [-h h1] ... [-m m]

summarizes free space for the filesystem 🌸 the free blocks get examined and totalled, then displayed as 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 you give no -a options, then all allocation groups get processed.
  • -b — the histogram buckets are binary-sized, with the starting sizes being the powers of 2.
  • -c — freesp will search the by-size (cnt) space Btree instead of the default by-block (bno) space Btree.
  • -d — every free extent will be displayed.
  • -e — the histogram buckets are equal-sized, with the size specified as i.
  • -h — says "this is where a histogram bucket starts", as h1. Stack up multiple -h's to lay out the entire set of buckets. 🪣
  • -m — says the histogram starting block numbers are powers of m. This is the glow-up general case of -b. ✨
  • -s — says to print a final summary of total free extents, free blocks, and the average free extent size at the end.

fsb

See the fsblock command. 👀

fsblock [fsb]

Sets the current address to the fsblock value you hand it in fsb. If you don't give a fsb value, it prints the current address, expressed as an fsb. The type gets set to data (uninterpreted, no thoughts, just vibes).

XFS filesystem block numbers are computed like this:

((agno << agshift) | agblock)

where agshift depends on the size of an allocation group. Use the convert command to go to and from this form. Block numbers given for file blocks (say, from the bmap command) are in this form. 💅

fsmap [-r] [start [end]]

Prints the mapping of disk blocks used by an XFS filesystem. The map lists every extent used by files, allocation group metadata, journalling logs, and static filesystem metadata, plus any regions that are just sitting there unused. All blocks, offsets, and lengths are in units of 512-byte blocks, no matter what the filesystem's block size is. 🗺️

The optional start and end arguments constrain the output to a particular range of disk blocks.

When the -r option is given, it prints the reverse mapping for the real-time device instead of the data device.

fuzz [-c] [-d] field action

Writes 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, it's giving instant gratification.

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 — skips write verifiers and CRC recalculation; this allows invalid data to be written to disk.
  • -d — skips write verifiers but does perform CRC recalculation; this allows invalid data to be written to disk so you can 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...

Creates 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 so it plays nice 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 isn't 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. Bestie behavior fr fr. 🫶

makecfg [path]

Writes a configuration file to the given path that can be re-read by mkfs.xfs for a future filesystem format attempt. This file will contain only user-visible features. Filesystem geometry information is not written to the configuration file. If no path is given, the configuration will be printed on standard output. 📝

info

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

inode [inode#]

Sets the current inode number. If no inode# is given, prints the current inode number.

Allocates inodes and puts them on the unlinked list. 🗑️

Options include:

  • -n — create this number of unlinked inodes. If not specified, 1 inode will be created.

label [label]

Sets 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 — using a longer label will result in truncation, and a warning will be issued. If no label is given, the current filesystem label is printed. 🏷️

In the current directory, creates 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]

Starts logging output to filename, stops logging, or prints the current logging status. 🪵

logblock [logbno]

Sets the 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 isn't specified, the log is reformatted to the current cycle. If the log stripe unit isn't 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 helps when diagnosing minimum log size calculation errors. 🔍

ls [-im] [paths]...

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

Lists 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

Walks 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

Pops location from the stack.

Prints field values. If no argument is given, prints all fields in the current structure. 🖨️

push [command]

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

q

See the quit command. 👀

quit

Exits xfs_db. 👋

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

Recovers the files given by the path arguments by copying them off 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's 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. 💖 (that's the tail end of the previous command, bestie — no cap, it really does try to keep all that stuff intact)

  • rgresv [rgno] — shows the per-rtgroup reservation size, plus the per-rtgroup reservation usage for whichever realtime allocation group you point at. Give it no argument and it just dumps the info for all the rtgroups, like a little group-chat roster 🫶
  • rtblock [rtbno] — moves the current address to the spot on the realtime device that rtbno says. This value must be a realtime block number, okay? No fudging. If you don't hand over an rtbno, it just prints the current address, expressed as an rtbno. Type gets set to data (uninterpreted, i.e. raw, no vibes applied) ✨
  • rtextent [rtxno] — same energy, but the address is given by rtextent: a linear address measured in units of realtime extents. No rtextent argument? Then it prints the current address expressed as an rtextent. Type is set to data (uninterpreted). 💅
  • ring [index] — shows the position ring (if you don't pass an index), or teleports you to the specific entry in the position ring given by index. It's giving "scroll to message" energy. 🎀
  • rtconvert type number [type number] ... type — converts one address form into another for realtime section addresses. The known types, with their 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, bestie. The compound form — more than three arguments — is so useful for stuff like convert rgno rg rgbno rgb rtblock. 👑

Realtime summary file location conversions follow these 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 info for a given rt bitmap block, you have to specify a log2(extent length) 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 go the other way — computing the rt bitmap block from a summary file location — the type/number pairs must be specified exactly in the order rsumlog, rsuminfo, rsumblock. Order matters, no skipping, periodt.

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 the max free extent length is 2^21 rtextents:

rtconvert rsumlog 21 rsuminfo 809 rsumblock 10 rbmblock
  • rtsb — sets the current address to the superblock header at the very start of the realtime volume. Iconic little landmark. 🌟
  • sb [agno] — sets the current address to the SB header in allocation group agno. No agno? Then it uses the current allocation group number. 😌
  • source source-file — processes commands from source-file. And yes, source commands can be nested. Inception but make it Unix. 🌀
  • stack — view the location stack. That's it, that's the whole thing. Short and powerful. 💫
  • type [type] — sets the current data type to type. No argument? It shows 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. Peep the TYPES section below for the whole breakdown on these. 🌈
  • timelimit [OPTIONS] — prints the minimum and maximum supported values for inode timestamps, quota expiration timers, and quota grace periods that this filesystem can handle. 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, all 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, removes a directory entry with the given name. Heads up: the file being targetted will not be put on the iunlink list. 👀
  • untorn_write_max [-b blockcount|-l logres] — with -l, compute the maximum (in fsblocks) untorn write we can emulate with copy on write, given a log reservation size (in bytes). With -b, compute the log reservation size that would be needed to emulate an untorn write of the given number of fsblocks. Two-way street, pick your lane. 🛣️
  • uuid [uuid | generate | rewrite | restore] — sets the filesystem universally unique identifier (UUID). The filesystem UUID can be used by mount(8) instead of using a device special file. You can set the uuid directly to the UUID you want, or auto-generate it with the generate option. Both of those options write the UUID into every copy of the superblock in the filesystem. On a CRC-enabled filesystem, this sets an incompatible superblock flag, and the filesystem will not be mountable with older kernels — fr fr, read that twice. You can revert it with the restore option, which copies the original UUID back into place and clears the incompatible flag as needed. rewrite copies the current UUID from the primary superblock to all the secondary copies of the superblock. And if you give no argument at all? It just prints the current filesystem UUID. 💜
  • version [feature | versionnum features2] — enables selected features for a filesystem (certain features can be enabled on an unmounted filesystem, after mkfs.xfs(8) has created it). Support for unwritten extents can be enabled with the extflg option. Support for version 2 log format can be enabled with the log2 option. Support for extended attributes can be enabled with the attr1 or attr2 option. Once enabled, extended attributes cannot be disabled — but you may toggle between attr1 and attr2 at will (though older kernels might not support the newer version, so, y'know, vibe check your kernel first).

No argument? Then the current version and feature bits get printed. With one argument, this command writes the updated version number into every copy of the superblock in the filesystem. With two arguments, they're used as numeric values for the versionnum and features2 bits respectively, and their string equivalent is reported — but no modifications are made. 🎀

  • write [-c|-d] [field value] ... — writes a value to disk. You can set specific fields in structures (struct mode), or set a whole block to data values (data mode), or set a block to string values (string mode, for symlink blocks). The operation happens immediately — there is no buffering, bestie. No undo. 💀

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 that 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, running write with no arguments gives you more info on the allowed commands. 🌀

  • -c — skip write verifiers and CRC recalculation; allows invalid data to be written to disk.
  • -d — skip write verifiers but do perform CRC recalculation. This allows invalid data to be written to disk to test detection of invalid data. (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 — directory blocks, for instance. So one "type" can be a whole little ensemble cast. 💅

agf

The AGF block is the header for block allocation information; it lives 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 — okay so the AGFL block is literally the block allocator's little emergency stash of block numbers 🎀. It lives in the fourth 512-byte block of each allocation group. Every entry in the active list is a block number within the allocation group that can be used for any purpose if space runs low. Which entries are active rn? The AGF block's fields flfirst, fllast, and flcount are the ones that designate that 💅. Entry space gets allocated in a circular manner within the AGFL block, periodt. Fields defined:
    • bno — array of all block numbers. Even those which are not active are printed, so yeah, you get the whole roster bestie 📋.
  • agi — the AGI block is the header for inode allocation information, and it sits 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. (ngl, it's just sitting there 🪑)
    • 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 again, iykyk. 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. (yes bestie, the order flips here — that's on purpose 🙈)
    • 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 💖

okay so a version 1 directory is literally a Btree situation where the directory data is just… embedded in the leaf blocks. no big deal. the root of the Btree lives in block 0 of the file. the index (aka the sort order) is the hash value of the entry name. every block starts with a blkinfo structure that has these fields:

  • forw — next sibling block, bestie.
  • back — previous sibling block.
  • magic — magic number for this block type.

the non-leaf (node) blocks are giving:

  • 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, and the hashval is the last hash value in that block.

and the leaf blocks? they're serving:

  • 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, periodt. 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, but 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 these 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 these fields: inumber, namelen, name, and tag. for freespace, there are these 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:

  • 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:

  • 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:

  • 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 these 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 these 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. 💅

okay bestie, the inode core is packed and we're going field by field, no skipping, periodt 💅

  • magic — the inode magic number, and it's literally 0x494e ('IN'). iconic.
  • mode — the mode and type of the file, exactly as spelled out in chmod(2), mknod(2) and stat(2).
  • version — inode version, so 1 or 2.
  • format — what flavour the u union data is: 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, but for a version 1 inode.
  • nlinkv2 — number of links to the file, for a version 2 inode.
  • projid_lo — the owner's project id (low word; version 2 inode only).
  • projid_hi — the owner's project id (high word; version 2 inode only).
  • uid — the owner's user id.
  • gid — the owner's group id.
  • atime — time last accessed (seconds and nanoseconds, fancy).
  • mtime — time last modified.
  • ctime — time created, or the inode was last modified.
  • size — number of bytes in the file.
  • nblocks — total number of blocks in the file, indirect and attribute included.
  • extsize — the 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, measured in 64-bit words from the start of u.
  • aformat — format of the attribute data: 1 = local attribute data, 2 = extent list, 3 = Btree root.
  • dmevmask — DMAPI event mask.
  • dmstate — DMAPI state info.
  • newrtbm — the file is the realtime bitmap and it's in "new" format.
  • prealloc — the file has preallocated data space after EOF.
  • realtime — the file's data lives in the realtime subvolume.
  • gen — inode generation number.

and now the u data fork union, which is giving "choose your own adventure" ✨

  • bmbt — bmap Btree root. It looks like a bmapbtd block with the redundant info removed.
  • bmx — array of extent descriptors.
  • dev — dev_t for the block or character device.
  • sfdir — shortform (in-inode) version 1 directory. It's a hdr holding the parent inode number and a count of active entries in the directory, then an array list of hdr.count entries. Each entry has inumber, namelen, and a name string.
  • sfdir2 — shortform (in-inode) version 2 directory. This one's a hdr with a count of active entries, an i8count of entries whose inumbers don't fit in a 32-bit value, plus the parent inode number — then an array list of hdr.count entries. Each entry has namelen, a saved offset used when the directory gets converted to a larger form, a name string, and the inumber.
  • symlink — symbolic link string value. cute.

and if the attribute fork exists, the a union has these 🎀

  • bmbt — bmap Btree root, same as above.
  • bmx — array of extent descriptors.
  • sfattr — shortform (in-inode) attribute values. It's a hdr with a totsize (total size in bytes) and a count of active entries, followed by an array list of hdr.count entries. Each entry has namelen, valuelen, root flag, name, and value.

🪵 log — bestie, just don't

Log blocks contain the journal entries for XFS. And honestly? It is not useful to poke at these with xfs_db, so use xfs_logprint(8) instead. trust. 💀

refcntbt — the reference count Btree, per allocation group

There's 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, plus by pointers from parent to child blocks. Every block has these 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, or 0 if there isn't one.
  • rightsib — right (logically higher) sibling block, or 0 if there isn't one.
  • 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 pointing to the next level in the Btree.

rtrefcbt — the realtime reference count Btree

There's one reference count Btree for the entire realtime device. Heads up: 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, plus by pointers from parent to child blocks. Each block has these 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 pointing to the next level in the Btree.

rmapbt — the reverse mapping Btree, per allocation group

There's 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. Blocks are linked to sibling left and right blocks at each level, plus by pointers from parent to child blocks. Each block has these 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 pointing to the next level in the Btree.

rtrmapbt 💜

so there's literally one reverse mapping Btree for each realtime group, bestie. the startblock and blockcount fields are 32 bits wide and they record blocks within a realtime group. the root of this Btree is the reverse-mapping inode, which lives in the metadata directory. blocks get linked to their sibling left and right blocks at every level, plus by pointers from parent to child blocks. each block has these 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 points at a file that contains the realtime bitmap. every single bit in that bitmap file controls the allocation of one realtime extent, and it's set == free. the bitmap is processed in 32-bit words, and the LSB of a word is used for the first extent controlled by that bitmap word. also the atime field of the realtime bitmap inode holds a counter that controls where the next new realtime file will start. slay.

rtsummary 🌸

if the filesystem has a realtime subvolume, then the rsumino field in the superblock points at a file that contains the realtime summary data. the summary file is a two-dimensional array of 16-bit values. each value counts the number of free extent runs (that's consecutive free realtime extents) of a given range of sizes that starts in a given bitmap block. the size ranges are binary buckets, where the 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. first dimension is the size range, 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, and it's 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).

symbolic link blocks are used only when the symbolic link value doesn't fit inside the inode. the block content is just the string value, periodt. bytes past the logical end of the symbolic link value have arbitrary values, so don't come for them.

text 💅

user file blocks, and other blocks whose type is unknown, get this type for display purposes in xfs_db. the block data is displayed in two columns: Hexadecimal format and printable ASCII chars. iconic honestly.

🔍 DIAGNOSTICS 🔍

so many messages can come from the blockget command, bestie. 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 — iykyk.

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 ✨

bestie if you wanna go deeper (and you KNOW you do 💅) here's the whole friend group:

  • mkfs.xfs(8) — makes the filesystem in the first place, the origin story 🌱
  • xfs_admin(8) — tweaks the label and UUID and stuff 🏷️
  • xfs_copy(8) — copies an XFS filesystem, whole thing, no cap 📋
  • xfs_logprint(8) — prints the log, for when you need to snoop on the journal 🔍
  • xfs_metadump(8) — dumps the metadata so you can ship it off to someone smarter 💌
  • xfs_ncheck(8) — checks inode numbers against the filesystem, very detective-core 🕵️
  • xfs_repair(8) — the one you call when things are lowkey falling apart 🚑
  • mount(8) — mounts the thing, obviously, the whole point 🗂️
  • chmod(2) — the syscall for changing file modes 🔐
  • mknod(2) — the syscall for making device nodes and stuff 🧱
  • stat(2) — the syscall for asking a file how it's doing 📊
  • xfs(5) — the XFS filesystem format deep dive, for the lore girlies 📚

and that's the whole page, bestie, we made it to the end 🎀 this one came from the xfs(8) family of man pages — source and version info live in that footer line at the bottom of the original, dated the usual manpage date spot. now go run it responsibly, back up your metadata first, and don't poke a live filesystem with a debugger unless you're ready for main character energy in the worst way 😭💖 slay, and see you in the next manpage 🦋

📦 where this page comes from