xfs_ncheck

xfs_ncheck [ -v ] [ -i inode# ] [ -s ] [ -o offset ] device

-v
    Enables verbose mode, providing more detailed output during the scan process.

-i inode#
    Specifies a particular inode number to look up. If this option is omitted, xfs_ncheck will scan all directories for potentially orphaned files or list all entries found.

-s
    Scans for orphaned files and prints their path names. This option is useful when xfs_repair has moved unreferenced files to the lost+found directory, and you want to identify their original paths.

-o offset
    Specifies a directory block offset within the filesystem to start scanning from. This is an advanced option typically used for debugging or very specific recovery scenarios.

device
    The XFS device special file (e.g., /dev/sda1, /dev/mapper/vg0-lv0) on which to perform the inode lookup or scan.

xfs_ncheck is a utility designed for the XFS filesystem that performs a reverse lookup, mapping inode numbers back to their corresponding path names. This command is particularly useful during filesystem inconsistencies, recovery operations, or when analyzing filesystem corruption where only inode numbers are known. It operates by scanning the directory entries of an XFS filesystem to find the given inode number and then constructing the full path to that inode. Unlike fsck utilities, xfs_ncheck does not modify the filesystem; it merely reports paths. It's often used in conjunction with tools like xfs_repair or xfs_check to help identify specific files associated with problem inodes. It can be used on a mounted or unmounted filesystem, though typically used on unmounted or read-only mounted filesystems for consistency and reliable results.

Running xfs_ncheck, especially the full scan without -i (i.e., with -s), can be very time-consuming on large filesystems due to the extensive directory traversal required.
It is generally recommended to run this command on an unmounted XFS filesystem or one mounted read-only to ensure consistent results and avoid issues with concurrent filesystem modifications.

This command is primarily used in recovery and troubleshooting scenarios. For instance, after xfs_repair has identified and potentially moved unreferenced inodes to the lost+found directory, xfs_ncheck can help identify the original file paths associated with those inode numbers, aiding in data recovery.

When invoked without a specific inode number (i.e., using the -s option to scan for all orphaned files), xfs_ncheck performs a full traversal of the filesystem's directory structure. This can be I/O intensive and take a significant amount of time on filesystems with many files or deep directory hierarchies. It is most efficient when used with the -i option to look up a single known inode.

xfs_ncheck is part of the xfsprogs suite, a collection of utilities for managing XFS filesystems. XFS itself was originally developed by Silicon Graphics (SGI) in the early 1990s for its IRIX operating system and later open-sourced, becoming a prominent journaling filesystem in the Linux kernel. The concept of an 'ncheck' utility (to reverse map inode numbers to path names) is a traditional feature found in Unix-like filesystem toolsets, assisting in recovery and diagnostics. xfs_ncheck provides this specific functionality tailored for the XFS filesystem structure.

xfs_check(8), xfs_repair(8), find(1), ls(1), debugfs(8)