xfs_io

xfs_io [ options ] [ file ]
xfs_io -c command [ options ] [ file ]
xfs_io -V

-r
    Opens the specified file in read-only mode.

-w
    Opens the specified file in read-write mode (default). This option is largely for completeness as write mode is the default.

-c <cmd> [args]
    Executes the specified command(s) and exits. Multiple -c options can be used to execute a sequence of commands.

-p <projid>
    Sets the project ID for subsequent operations, affecting project quota management.

-v
    Enables verbose output, showing more details about operations.

-s
    Prints I/O statistics after operations complete.

-f
    Forces direct I/O, bypassing the operating system's page cache. This is useful for performance testing.

-x
    Enables extended debug output, useful for developers and advanced troubleshooting.

-D
    Operates on a raw device (e.g., a partition) instead of a file, typically to inspect or modify the superblock or other device-level structures.

-V
    Prints the xfs_io version information and exits.

allocsp <offset> <length>
    Allocates space for a file from offset for length bytes. This is a sparse allocation, meaning blocks are not necessarily written to.

falloc <offset> <length>
    Preallocates disk space for a file, similar to posix_fallocate(3). The space is guaranteed to be reserved and zeroed.

fiemap [options] <offset> <length>
    Displays the extent mapping for a file, showing on-disk locations and sizes of allocated blocks.

pwrite <offset> <length> [pattern]
    Writes length bytes of data at offset to the file. An optional pattern (e.g., '0xdeadbeef', 'a', '0') can be specified for the data.

pread <offset> <length>
    Reads length bytes of data from the file starting at offset and prints it to standard output. Data is typically displayed in hexadecimal and ASCII.

seek <offset>
    Changes the current file offset for subsequent read/write operations.

getxattr <attr_name>
    Retrieves and displays the value of an extended attribute associated with the file.

setxattr <attr_name> <attr_value>
    Sets an extended attribute with the specified name and value on the file.

fsync
    Synchronizes all dirty data and metadata (including directory entries) to disk for the current file.

fdatasync
    Synchronizes all dirty data to disk for the current file, but not necessarily metadata that is not required for subsequent access.

zero <offset> <length>
    Zeros out a specified region of the file from offset for length bytes.

stat
    Displays detailed status information (like inode number, size, permissions, links, etc.) about the current file.

lsattr
    Lists XFS-specific file attributes (e.g., noatime, append-only, immutable). Also known as inode flags.

chattr <attr_flags>
    Changes XFS-specific file attributes based on the provided flags (e.g., '+i' for immutable, '-a' for no append-only).

quit | exit
    Exits the xfs_io interactive shell.

xfs_io is a powerful diagnostic and debugging tool for the XFS filesystem. It allows users to perform various I/O operations and examine file system metadata directly on a mounted XFS filesystem. This includes reading and writing blocks, manipulating file attributes, managing extended attributes, and performing low-level operations like preallocation, writeback, and data zeroing. It is invaluable for testing filesystem behavior, reproducing issues, and understanding XFS internals, making it a critical utility for developers and system administrators. xfs_io can operate on files, directories, or block devices and supports both interactive and non-interactive modes of operation. It offers a wide range of internal commands for fine-grained control over XFS-specific features.

Most operations of xfs_io, especially those involving writes or direct device access (-D), require root privileges.
Improper use of xfs_io, particularly write commands or operations on raw devices, can lead to data corruption or filesystem damage. It is a low-level tool intended for experienced users and developers.
xfs_io is specific to XFS filesystems and will not work on other filesystem types (e.g., ext4, Btrfs).

When invoked without the -c option and with a file argument, xfs_io enters an interactive shell (e.g., xfs_io>). This mode allows users to execute multiple commands sequentially on the specified file or device without re-invoking the utility for each command. This is highly beneficial for complex debugging or testing scenarios.

xfs_io provides detailed error messages when operations fail, often mapping directly to standard Unix errno values (e.g., 'Permission denied', 'No space left on device') or XFS-specific error codes. This verbosity is crucial for diagnosing issues at a low level.

XFS is a high-performance 64-bit journaling filesystem created by Silicon Graphics, Inc. (SGI) for their IRIX operating system. It was ported to Linux in 2001 and has since become a mature and widely used filesystem, especially for large files and high-concurrency workloads. xfs_io is part of the xfsprogs package, which provides a suite of utilities for XFS filesystem management. Its development has mirrored the evolution and maintenance of XFS itself, focusing on providing robust low-level diagnostic and testing capabilities for filesystem developers and system administrators.

xfs_info(8), xfs_db(8), xfs_fsr(8), xfs_ncheck(8), xfs(5), ioctl(2), dd(1)