linux-file-handle · shipping · also Linux file_handle, name_to_handle_at, open_by_handle_at

Linux file handle

A Linux file handle is an opaque filesystem-specific object identifier that can be used for later reopening when the filesystem and handle type support it.

name_to_handle_at() returns a handle and mount identifier; open_by_handle_at() interprets the handle in a mounted filesystem and returns a new descriptor. AT_HANDLE_FID (since Linux 6.5) requests identity without promising reopening. AT_HANDLE_CONNECTABLE (since Linux 6.13) handles can fail after a move to another parent. The ordinary mount ID is not a persistent filesystem identifier. [1]

Saving handle bytes does not retain an open reference. Linux v6.8 releases the pathname lookup reference after encoding, and resolves the object again on reopening. A handle is not an open file description, a backup copy or a frozen content version. [4] Kernel export operations encode and reconstruct filesystem objects rather than saving their pathnames. [2]

In Linux v6.8 ext4, ext4_nfs_get_inode rejects a supplied nonzero generation when it differs from the inode's generation. The zero-generation case skips that comparison; this is not a universal handle layout or a content-version check. [3]

AT_HANDLE_MNT_ID_UNIQUE (since Linux 6.12) requires a mount_id output buffer of at least 64 bits. It returns the identifier exposed by statx STATX_MNT_ID_UNIQUE (since Linux 6.8), whose no-reuse guarantee lasts while the system is running. This identifies a mount instance, not a persistent filesystem across reboot or an unmount/mount cycle. [1] [5]

EOVERFLOW can mean either insufficient handle storage or no handle available for the queried name. In the latter case handle_bytes does not increase; blindly enlarging the buffer is not a general recovery strategy. [1]

Relations

related

Inode, Open file description, File descriptor, Path resolution, Filesystem UUID, Unlink

Advantages

• Can identify an object without depending solely on its current pathname.

Limitations

• Reopening depends on filesystem support, suitable mount context, the required capability and applicable open checks; the documented API requires CAP_DAC_READ_SEARCH.
• ESTALE reports an unusable handle, not proof of disk damage or a recoverable deleted file. [1]

Citations

1. Linux man-pages: name_to_handle_at(2) and open_by_handle_at(2), identity, flags and stale handles (accessed 2026-11-09)
2. Linux 6.13 documentation: Making Filesystems Exportable, references and filehandle fragments (accessed 2026-11-09)
3. Linux v6.8: ext4_nfs_get_inode generation validation (accessed 2026-11-09)
4. Linux v6.8: name_to_handle_at drops the lookup reference; handle reopening resolves the filesystem object again (accessed 2026-11-09)
5. Linux man-pages: statx(2), unique mount identifier and runtime no-reuse guarantee (accessed 2026-11-09)

JSON: /data/terms/linux-file-handle.json