1 .\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer
2 .\" Description based on include/uapi/fuse.h and code in fs/fuse
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH FUSE 4 2018-02-02 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
8 fuse \- Filesystem in Userspace (FUSE) device
11 .B #include <linux/fuse.h>
14 This device is the primary interface between the FUSE filesystem driver
15 and a user-space process wishing to provide the filesystem (referred to
16 in the rest of this manual page as the
17 .IR "filesystem daemon" ).
18 This manual page is intended for those
19 interested in understanding the kernel interface itself.
20 Those implementing a FUSE filesystem may wish to make use of
21 a user-space library such as
23 that abstracts away the low-level interface.
25 At its core, FUSE is a simple client-server protocol, in which the Linux
26 kernel is the client and the daemon is the server.
27 After obtaining a file descriptor for this device, the daemon may
29 requests from that file descriptor and is expected to
32 It is important to note that a file descriptor is
33 associated with a unique FUSE filesystem.
34 In particular, opening a second copy of this device,
35 will not allow access to resources created
36 through the first file descriptor (and vice versa).
38 .SS The basic protocol
39 Every message that is read by the daemon begins with a header described by
40 the following structure:
44 struct fuse_in_header {
45 uint32_t len; /* Total length of the data,
46 including this header */
47 uint32_t opcode; /* The kind of operation (see below) */
48 uint64_t unique; /* A unique identifier for this request */
49 uint64_t nodeid; /* ID of the filesystem object
51 uint32_t uid; /* UID of the requesting process */
52 uint32_t gid; /* GID of the requesting process */
53 uint32_t pid; /* PID of the requesting process */
59 The header is followed by a variable-length data portion
60 (which may be empty) specific to the requested operation
61 (the requested operation is indicated by
64 The daemon should then process the request and if applicable send
65 a reply (almost all operations require a reply; if they do not,
66 this is documented below), by performing a
68 to the file descriptor.
69 All replies must start with the following header:
73 struct fuse_out_header {
74 uint32_t len; /* Total length of data written to
75 the file descriptor */
76 int32_t error; /* Any error that occurred (0 if none) */
77 uint64_t unique; /* The value from the
78 corresponding request */
83 This header is also followed by (potentially empty) variable-sized
84 data depending on the executed request.
85 However, if the reply is an error reply (i.e.,
88 then no further payload data should be sent, independent of the request.
90 .SS Exchanged messages
91 This section should contain documentation for each of the messages
93 This manual page is currently incomplete,
94 so not all messages are documented.
95 For each message, first the struct sent by the kernel is given,
96 followed by a description of the semantics of the message.
102 struct fuse_init_in {
105 uint32_t max_readahead; /* Since protocol v7.6 */
106 uint32_t flags; /* Since protocol v7.6 */
111 This is the first request sent by the kernel to the daemon.
112 It is used to negotiate the protocol version and other filesystem parameters.
113 Note that the protocol version may affect the layout of any structure
114 in the protocol (including this structure).
115 The daemon must thus remember the negotiated version
116 and flags for each session.
117 As of the writing of this man page,
118 the highest supported kernel protocol version is
121 Users should be aware that the descriptions in this manual page
122 may be incomplete or incorrect for older or more recent protocol versions.
124 The reply for this request has the following format:
128 struct fuse_init_out {
131 uint32_t max_readahead; /* Since v7.6 */
132 uint32_t flags; /* Since v7.6; some flags bits
133 were introduced later */
134 uint16_t max_background; /* Since v7.13 */
135 uint16_t congestion_threshold; /* Since v7.13 */
136 uint32_t max_write; /* Since v7.5 */
137 uint32_t time_gran; /* Since v7.6 */
143 If the major version supported by the kernel is larger than that supported
144 by the daemon, the reply shall consist of only
146 (following the usual header),
147 indicating the largest major version supported by the daemon.
148 The kernel will then issue a new
150 request conforming to the older version.
151 In the reverse case, the daemon should
152 quietly fall back to the kernel's major version.
154 The negotiated minor version is considered to be the minimum
155 of the minor versions provided by the daemon and the kernel and
156 both parties should use the protocol corresponding to said minor version.
162 struct fuse_getattr_in {
163 uint32_t getattr_flags;
165 uint64_t fh; /* Set only if
166 (getattr_flags & FUSE_GETATTR_FH)
171 The requested operation is to compute the attributes to be returned
174 and similar operations for the given filesystem object.
175 The object for which the attributes should be computed is indicated
180 flag is set, by the file handle
182 The latter case of operation is analogous to
185 For performance reasons, these attributes may be cached in the kernel for
186 a specified duration of time.
187 While the cache timeout has not been exceeded,
188 the attributes will be served from the cache and will not cause additional
192 The computed attributes and the requested
193 cache timeout should then be returned in the following structure:
197 struct fuse_attr_out {
198 /* Attribute cache duration (seconds + nanoseconds) */
200 uint32_t attr_valid_nsec;
228 struct fuse_access_in {
236 .I default_permissions
237 mount options is not used, this request may be used for permissions checking.
238 No reply data is expected, but errors may be indicated
239 as usual by setting the
241 field in the reply header (in particular, access denied errors
242 may be indicated by returning
245 .BR FUSE_OPEN " and " FUSE_OPENDIR
248 struct fuse_open_in {
249 uint32_t flags; /* The flags that were passed
256 The requested operation is to open the node indicated by
257 .IR header\->nodeid .
258 The exact semantics of what this means will depend on the
259 filesystem being implemented.
260 However, at the very least the
261 filesystem should validate that the requested
263 are valid for the indicated resource and then send a reply with the
268 struct fuse_open_out {
278 field is an opaque identifier that the kernel will use to refer
282 field is a bit mask of any number of the flags
283 that indicate properties of this file handle to the kernel:
287 Bypass page cache for this open file.
290 Don't invalidate the data cache on open.
293 The file is not seekable.
296 .BR FUSE_READ " and " FUSE_READDIR
300 struct fuse_read_in {
312 The requested action is to read up to
314 bytes of the file or directory, starting at
316 The bytes should be returned directly following the usual reply header.
321 struct fuse_interrupt_in {
327 The requested action is to cancel the pending operation indicated by
329 This request requires no response.
330 However, receipt of this message does
331 not by itself cancel the indicated operation.
332 The kernel will still expect a reply to said operation (e.g., an
334 error or a short read).
337 request will be issued for a given operation.
338 After issuing said operation,
339 the kernel will wait uninterruptibly for completion of the indicated request.
342 Directly following the header is a filename to be looked up in the directory
344 .IR header\->nodeid .
345 The expected reply is of the form:
349 struct fuse_entry_out {
350 uint64_t nodeid; /* Inode ID */
351 uint64_t generation; /* Inode generation */
352 uint64_t entry_valid;
354 uint32_t entry_valid_nsec;
355 uint32_t attr_valid_nsec;
356 struct fuse_attr attr;
365 must be unique for the filesystem's lifetime.
367 The interpretation of timeouts and
375 struct fuse_flush_in {
384 The requested action is to flush any pending changes to the indicated
386 No reply data is expected.
387 However, an empty reply message
388 still needs to be issued once the flush operation is complete.
390 .BR FUSE_RELEASE " and " FUSE_RELEASEDIR
393 struct fuse_release_in {
396 uint32_t release_flags;
402 These are the converse of
407 The daemon may now free any resources associated with the
410 as the kernel will no longer refer to it.
411 There is no reply data associated with this request,
412 but a reply still needs to be issued once the request has
413 been completely processed.
416 This operation implements
419 There is no input data associated with this request.
420 The expected reply data has the following structure:
424 struct fuse_kstatfs {
437 struct fuse_statfs_out {
438 struct fuse_kstatfs st;
443 For the interpretation of these fields, see
450 operations when the kernel's request is too large for the provided buffer
457 if validation of the reply failed.
458 Not all mistakes in replies will be caught by this validation.
459 However, basic mistakes, such as short replies or an incorrect
466 operations when the kernel's request is too large for the provided buffer.
469 There are various ways in which incorrect use of these interfaces can cause
470 operations on the provided filesystem's files and directories to fail with
472 Among the possible incorrect uses are:
477 for an inode that has previously been reported to the kernel; or
479 giving replies to the kernel that are shorter than what the kernel expected.
487 if the FUSE filesystem was unmounted.
490 Returned from operations on a
492 file descriptor that has not been mounted.
494 The FUSE filesystem is Linux-specific.
496 The following messages are not yet documented in this manual page:
498 .\" FIXME: Document the following.