xref: /linux/Documentation/filesystems/fuse-io.rst (revision 24168c5e6dfbdd5b414f048f47f75d64533296ca)
1.. SPDX-License-Identifier: GPL-2.0
2
3==============
4Fuse I/O Modes
5==============
6
7Fuse supports the following I/O modes:
8
9- direct-io
10- cached
11  + write-through
12  + writeback-cache
13
14The direct-io mode can be selected with the FOPEN_DIRECT_IO flag in the
15FUSE_OPEN reply.
16
17In direct-io mode the page cache is completely bypassed for reads and writes.
18No read-ahead takes place. Shared mmap is disabled by default. To allow shared
19mmap, the FUSE_DIRECT_IO_ALLOW_MMAP flag may be enabled in the FUSE_INIT reply.
20
21In cached mode reads may be satisfied from the page cache, and data may be
22read-ahead by the kernel to fill the cache.  The cache is always kept consistent
23after any writes to the file.  All mmap modes are supported.
24
25The cached mode has two sub modes controlling how writes are handled.  The
26write-through mode is the default and is supported on all kernels.  The
27writeback-cache mode may be selected by the FUSE_WRITEBACK_CACHE flag in the
28FUSE_INIT reply.
29
30In write-through mode each write is immediately sent to userspace as one or more
31WRITE requests, as well as updating any cached pages (and caching previously
32uncached, but fully written pages).  No READ requests are ever sent for writes,
33so when an uncached page is partially written, the page is discarded.
34
35In writeback-cache mode (enabled by the FUSE_WRITEBACK_CACHE flag) writes go to
36the cache only, which means that the write(2) syscall can often complete very
37fast.  Dirty pages are written back implicitly (background writeback or page
38reclaim on memory pressure) or explicitly (invoked by close(2), fsync(2) and
39when the last ref to the file is being released on munmap(2)).  This mode
40assumes that all changes to the filesystem go through the FUSE kernel module
41(size and atime/ctime/mtime attributes are kept up-to-date by the kernel), so
42it's generally not suitable for network filesystems.  If a partial page is
43written, then the page needs to be first read from userspace.  This means, that
44even for files opened for O_WRONLY it is possible that READ requests will be
45generated by the kernel.
46