{
  "slug": "io-uring-registered-files",
  "term": "io_uring registered files",
  "aliases": [
    "io_uring fixed files",
    "io_uring direct descriptors"
  ],
  "definition": "io_uring registered files are file references held in a ring-local table and addressed by table index for supported requests.",
  "note": "Identity: IOSQE_FIXED_FILE makes the SQE fd field a registered-table index, not a process file descriptor. Registering process fd 17 in slot 0 therefore makes 0 the fixed-file selector; 17 is not the slot number. [register-api]\n\nLifetime: registration takes its own reference to the same open file description, not an independent open with a separate offset. Closing the original process descriptor does not remove that table entry. Requests already holding a resource retain it across replacement; a merely prepared SQE does not freeze the slot's identity. [registered-source] [registered-lookup]\n\nUpdates: the helper reports an updated-entry count or a negative errno. Check it against the requested count. Linux v6.16 removes an old slot before looking up its replacement; failure can leave that slot empty, so an update is not an all-or-nothing transaction. IORING_REGISTER_FILES_SKIP advances the processed count without changing that slot; a positive count is not the number of changed references. [register-helper] [registered-source]\n\nNotifications: replacing a nonzero-tagged resource can produce a CQE carrying its old tag after outstanding uses finish. This is a resource-retirement notification, not the byte count or synchronization result of an I/O request. [register-api]",
  "status": "shipping",
  "advantages": [
    "Reduces repeated file-reference management for operations using the registered table."
  ],
  "limitations": [
    {
      "text": "A direct descriptor selects a ring-local file reference; it does not itself enable O_DIRECT or bypass the page cache.",
      "citationIds": [
        "direct-open"
      ]
    }
  ],
  "related": [
    "io-uring",
    "file-descriptor",
    "io-uring-cqe",
    "direct-io"
  ],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-08",
  "citations": [
    {
      "id": "register-api",
      "title": "liburing 2.8: io_uring_register(2), registered files and resource tags",
      "url": "https://github.com/axboe/liburing/blob/liburing-2.8/man/io_uring_register.2",
      "accessed": "2026-11-08"
    },
    {
      "id": "register-helper",
      "title": "liburing 2.8: io_uring_register_files(3), registration and update return values",
      "url": "https://github.com/axboe/liburing/blob/liburing-2.8/man/io_uring_register_files.3",
      "accessed": "2026-11-08"
    },
    {
      "id": "registered-source",
      "title": "Linux v6.16: io_sqe_files_register, __io_sqe_files_update and io_free_rsrc_node",
      "url": "https://github.com/torvalds/linux/blob/v6.16/io_uring/rsrc.c",
      "accessed": "2026-11-08"
    },
    {
      "id": "registered-lookup",
      "title": "Linux v6.16: io_assign_file and io_file_get_fixed",
      "url": "https://github.com/torvalds/linux/blob/v6.16/io_uring/io_uring.c",
      "accessed": "2026-11-08"
    },
    {
      "id": "direct-open",
      "title": "liburing 2.8: io_uring_prep_openat(3), direct descriptors and ordinary descriptors",
      "url": "https://github.com/axboe/liburing/blob/liburing-2.8/man/io_uring_prep_openat.3",
      "accessed": "2026-11-08"
    },
    {
      "id": "hesela-uring",
      "title": "Hesela: io_uring completion and durability boundaries",
      "url": "https://hesela.com/analyses/io-uring-completion-ordering-durability/",
      "accessed": "2026-11-08"
    }
  ],
  "provenance": [
    "API and pinned implementation review; no kernel execution, throughput benchmark or persistence experiment was performed."
  ]
}