{
  "slug": "linux-file-handle",
  "term": "Linux file handle",
  "aliases": [
    "Linux file_handle",
    "name_to_handle_at",
    "open_by_handle_at"
  ],
  "definition": "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.",
  "note": "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. [handle-api]\n\nSaving 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. [handle-lifetime] Kernel export operations encode and reconstruct filesystem objects rather than saving their pathnames. [export-ops]\n\nIn 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. [ext4-handle]\n\nAT_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. [handle-api] [statx-mount-id]\n\nEOVERFLOW 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. [handle-api]",
  "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. [handle-api]"
  ],
  "related": [
    "inode",
    "open-file-description",
    "file-descriptor",
    "path-resolution",
    "filesystem-uuid",
    "unlink"
  ],
  "citations": [
    {
      "id": "handle-api",
      "title": "Linux man-pages: name_to_handle_at(2) and open_by_handle_at(2), identity, flags and stale handles",
      "url": "https://man7.org/linux/man-pages/man2/open_by_handle_at.2.html",
      "accessed": "2026-11-09"
    },
    {
      "id": "export-ops",
      "title": "Linux 6.13 documentation: Making Filesystems Exportable, references and filehandle fragments",
      "url": "https://docs.kernel.org/6.13/filesystems/nfs/exporting.html",
      "accessed": "2026-11-09"
    },
    {
      "id": "ext4-handle",
      "title": "Linux v6.8: ext4_nfs_get_inode generation validation",
      "url": "https://github.com/torvalds/linux/blob/v6.8/fs/ext4/super.c#L1436-L1453",
      "accessed": "2026-11-09"
    },
    {
      "id": "handle-lifetime",
      "title": "Linux v6.8: name_to_handle_at drops the lookup reference; handle reopening resolves the filesystem object again",
      "url": "https://github.com/torvalds/linux/blob/v6.8/fs/fhandle.c",
      "accessed": "2026-11-09"
    },
    {
      "id": "statx-mount-id",
      "title": "Linux man-pages: statx(2), unique mount identifier and runtime no-reuse guarantee",
      "url": "https://man7.org/linux/man-pages/man2/statx.2.html",
      "accessed": "2026-11-09"
    }
  ],
  "status": "shipping",
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-09",
  "provenance": [
    "API and version-pinned source synthesis, not a native syscall or recovery experiment.",
    "Human explanation: https://hesela.com/analyses/atomic-rename-directory-durability/#saved-file-handle"
  ]
}