direct-io · shipping · also O_DIRECT

Direct I/O

Direct I/O is a file-access mode, such as Linux O_DIRECT, that requests I/O through user-space buffers while minimizing use of the local operating-system page cache.

Linux O_DIRECT has been supported since 2.4.10. It transfers through user-space buffers to reduce local page-cache use. Performance is workload-dependent; keep it an optional optimization. O_DIRECT alone lacks O_SYNC durability semantics. [1]

Alignment varies by filesystem and kernel. Historical Linux 2.4 generally used filesystem-block alignment (often 4096 bytes); 2.6.0 relaxed this to logical-device blocks (often 512 bytes). These are not universal defaults. Misalignment may fail with EINVAL or use buffering; unsupported filesystems can reject open() with EINVAL. Since 6.1, statx can report per-file requirements. Check returned mask bits: absent STATX_DIOALIGN means unknown; reported zero base fields mean unsupported. Read-specific alignment does not relax buffer alignment. [1] [5]

NFS O_DIRECT bypasses only the client page cache; the flag is not sent to the server. OpenZFS v2.3 can verify in-flight direct-write buffers and report errors through zpool status -d; such errors alone do not identify media damage. [2] [4]

A failed direct write can partially modify the attempted range. Treat it as potentially inconsistent: the error alone neither proves corruption nor gives a completed-byte count. Positive short results report transferred bytes, not by themselves durability. Interpret errno and the failure stage separately. [7]

Linux v6.17 iomap tracks bio errors separately from submitted size; completion can return an error instead of that total, with filesystem hooks participating. Retain intended offset, length and payload for recovery rather than assuming rollback. [8]

Relations

related
Block storage, Solid-state drive (SSD), fsync, Write-back cache, Write-through cache, Partition alignment, 512e emulation, 4Kn native sectors, Queue depth, NVMe, NFS, Fault injection, Direct-I/O alignment, Buffered I/O, Page cache, NFS attribute cache, RWF_HIPRI, KVell, FILE_FLAG_NO_BUFFERING

Advantages

  • Avoids double buffering when an application, such as a database, manages its own cache
  • Can bypass the local page cache where the filesystem supports direct I/O; remote-server and device caches are separate.
  • Linux 6.1 and later can report alignment requirements per file via statx() STATX_DIOALIGN

Limitations

  • Performance depends on request sizes, caching and concurrency; compare equivalent workloads and completion requirements.
  • Not a durability guarantee by itself; O_SYNC must be added to guarantee data and metadata transfer
  • Offset, length and buffer alignment rules vary by filesystem and kernel; misaligned I/O can fail with EINVAL or fall back to buffered I/O
  • Mixing O_DIRECT with buffered I/O or mmap on the same file is discouraged, and private-buffer O_DIRECT I/O must not run concurrently with fork()

Citations

  1. open(2) — open, openat, creat (Linux man-pages, O_DIRECT section; Debian bookworm manpages-dev) (accessed 2026-10-11)
  2. Linux man-pages open(2), Debian trixie: O_DIRECT and NFS client/server cache scope. (accessed 2026-10-12)
  3. OpenZFS v2.3 zfs(4), zfs_vdev_direct_write_verify: in-flight buffer verification (accessed 2026-10-14)
  4. Linux man-pages: statx(2), returned masks and direct-I/O alignment fields. (accessed 2026-10-14)
  5. Linux man-pages 6.19: write(2), return values and direct-I/O error warning (accessed 2026-11-08)
  6. Linux v6.17: iomap direct-I/O submission, bio error collection and completion (accessed 2026-11-08)

Further reading

  1. NFS stable writes: what COMMIT, flush and FUA actually promise (accessed 2026-10-12)
  2. O_DIRECT alignment: query the file, not a fixed block size (accessed 2026-10-14)
Sources & caveats
  • The error explanation is based on Linux man-pages and the v6.17 iomap implementation, not native fault injection or measured persisted-byte coverage. [7] [8]

JSON: /data/terms/direct-io.json

Published by Hesela team · Updated

Report a correction · Editorial standards · Reuse guidance

Cite this page
Hesela team. Direct I/O. Hesela. 2026-11-14. https://hesela.dev/terms/direct-io/