Inodes

A directory on ext4, XFS, btrfs or APFS is a list of (name, inode number) pairs — a hash-indexed tree on ext4 (dir_index), a B+tree on XFS. The name resolves to a number; the number indexes the file system’s inode table (ext4) or inode B-tree (XFS, btrfs). The inode is the record found there. It is the file; the name is a pointer to it, and there may be several such pointers or, transiently, none (Files, Paths and Names).

What the inode holds: mode (type — regular, directory, symlink, device, socket, FIFO — and the permission bits), uid/gid, size in bytes, timestamps (atime last access, mtime last content change, ctime last inode change; ext4 also has a creation time visible via statx), link count, the number of blocks allocated, and the block map. What it does not hold: its name, and its path. stat prints all of it; ls -i prints just the number.

The inode number is unique within one file system, not across the machine. Two files on different mounts can share number 12; the pair (device, inode) is the real identity, which is what rsync, tar and backup tools use to recognise hard links and what find -samefile compares. On XFS the inode number encodes its location (allocation group, block, offset), which is why XFS numbers are large and sparse.

The classic Unix block map, still used by ext2 and ext3, is an array inside the inode: 12 direct pointers to data blocks, then one pointer to a single-indirect block (itself a block full of 1024 pointers with 4 KiB blocks and 4-byte addresses), one to a double-indirect block (1024 × 1024), and one to a triple-indirect block. Small files — the vast majority — need only the direct pointers; the first 48 KiB is reachable with zero extra reads, the next 4 MiB with one, and so on up to about 4 TiB. Reading byte 3 GB of a file means following three levels of pointers, each a potential disk read.

The cost is that a contiguous 1 GB file still needs 262,144 individual pointers spread across indirect blocks, all of which must be read to map it, and all of which must be written to free it (deleting a large file on ext3 was famously slow). Extents replace the pointer array with (logical block, physical block, length) triples: one entry can describe up to 128 MiB of contiguous space on ext4. The inode holds four extents inline; larger or fragmented files spill into an extent tree, a B+tree whose leaves are extents. XFS, btrfs, APFS and NTFS all use extent-shaped maps in their own tree structures.

Extents are why fragmentation matters again in a way it did not on a fresh pointer-based file system: a file appended in tiny increments while other files are also growing ends up with thousands of short extents, and its read pattern becomes random rather than sequential. filefrag -v shows the map; e4defrag and XFS’s xfs_fsr rewrite files contiguously. Preallocation (fallocate) is how databases and log writers reserve a contiguous run up front.

The link count in the inode is the number of directory entries that point at it. ln adds an entry and increments it; rm — unlink(2) — removes an entry and decrements it. Nothing about the data changes until the count hits zero and the last open descriptor closes; only then are the blocks returned to the free bitmap and the inode itself freed. A directory’s count starts at 2 (its own entry in the parent, plus its own .) and grows by one for every subdirectory’s .., which is why ls -ld on a directory with 5 subdirectories shows 7.

Hard links cannot cross file systems (an inode number means nothing on another device) and, on almost every system, cannot point at directories (it would create cycles that .. could not resolve). Symbolic links have neither restriction because they are separate inodes whose data is a path string; that is why ls -l on a symlink shows a size equal to the target path’s length and why a symlink survives its target being deleted — as a dangling pointer.

The link count is also a correctness tool. Package managers and content-addressed stores (Nix, pnpm’s node_modules, Git’s object store on the same volume) deduplicate by hard-linking identical files; a build directory with 40,000 files can cost almost nothing in blocks. The trap is that editing "one" of them edits all of them — tools that care copy-on-write first (cp --reflink on btrfs/XFS/APFS does this at the block level).

ext4 decides how many inodes exist when the file system is created: by default one inode per 16 KiB of space (-i in mkfs.ext4), stored in fixed inode tables inside each block group. A 100 GB volume gets about 6.5 million inodes. That is plenty for a workstation and hopeless for a mail spool, a PHP session directory, a CI cache, a Docker overlay directory or a node_modules tree with millions of 200-byte files: each consumes a whole inode and a whole 4 KiB block, and the inode table fills while most of the bitmap is still zero. touch then fails with ENOSPC — the same error as a full disk — and df -h shows space free.

df -i shows the inode count and usage; a IUse% of 100 with a Use% of 40 is the diagnosis. The cure is finding and deleting (or archiving into a single tarball) the directory with the most small files — find / -xdev -printf '%h\n' | sort | uniq -c | sort -rn | head — because you cannot add inodes to an existing ext4 volume without reformatting. XFS allocates inode chunks on demand and is limited only by a percentage of the volume (maxpct, default 25%); btrfs has no fixed inode limit at all. That is a real reason to choose XFS for a small-file-heavy volume.

The mirror-image failure is also real: a volume formatted with a large inode ratio for a media library cannot then host a source tree. Both are decided at mkfs time and both are invisible until they are not. tune2fs -l shows the numbers for ext4; check them before you commit a volume to a workload.