1fuse(4) Kernel Interfaces Manual fuse(4)
2
6 fuse - Filesystem in Userspace (FUSE) device
7
9 #include <linux/fuse.h>
10
12 This device is the primary interface between the FUSE filesystem driver
13 and a user-space process wishing to provide the filesystem (referred to
14 in the rest of this manual page as the filesystem daemon). This manual
15 page is intended for those interested in understanding the kernel in‐
16 terface itself. Those implementing a FUSE filesystem may wish to make
17 use of a user-space library such as libfuse that abstracts away the
18 low-level interface.
19 At its core, FUSE is a simple client-server protocol, in which the
21 Linux kernel is the client and the daemon is the server. After obtain‐
22 ing a file descriptor for this device, the daemon may read(2) requests
23 from that file descriptor and is expected to write(2) back its replies.
24 It is important to note that a file descriptor is associated with a
25 unique FUSE filesystem. In particular, opening a second copy of this
26 device, will not allow access to resources created through the first
27 file descriptor (and vice versa).
28 The basic protocol
30 Every message that is read by the daemon begins with a header described
31 by the following structure:
32 struct fuse_in_header {
34 uint32_t len; /* Total length of the data,
35 including this header */
36 uint32_t opcode; /* The kind of operation (see below) */
37 uint64_t unique; /* A unique identifier for this request */
38 uint64_t nodeid; /* ID of the filesystem object
39 being operated on */
40 uint32_t uid; /* UID of the requesting process */
41 uint32_t gid; /* GID of the requesting process */
42 uint32_t pid; /* PID of the requesting process */
43 uint32_t padding;
44 };
45 The header is followed by a variable-length data portion (which may be
47 empty) specific to the requested operation (the requested operation is
48 indicated by opcode).
49 The daemon should then process the request and if applicable send a re‐
51 ply (almost all operations require a reply; if they do not, this is
52 documented below), by performing a write(2) to the file descriptor.
53 All replies must start with the following header:
54 struct fuse_out_header {
56 uint32_t len; /* Total length of data written to
57 the file descriptor */
58 int32_t error; /* Any error that occurred (0 if none) */
59 uint64_t unique; /* The value from the
60 corresponding request */
61 };
62 This header is also followed by (potentially empty) variable-sized data
64 depending on the executed request. However, if the reply is an error
65 reply (i.e., error is set), then no further payload data should be
66 sent, independent of the request.
67 Exchanged messages
69 This section should contain documentation for each of the messages in
70 the protocol. This manual page is currently incomplete, so not all
71 messages are documented. For each message, first the struct sent by
72 the kernel is given, followed by a description of the semantics of the
73 message.
74 FUSE_INIT
76 struct fuse_init_in {
78 uint32_t major;
79 uint32_t minor;
80 uint32_t max_readahead; /* Since protocol v7.6 */
81 uint32_t flags; /* Since protocol v7.6 */
82 };
83 This is the first request sent by the kernel to the daemon. It
85 is used to negotiate the protocol version and other filesystem
86 parameters. Note that the protocol version may affect the lay‐
87 out of any structure in the protocol (including this structure).
88 The daemon must thus remember the negotiated version and flags
89 for each session. As of the writing of this man page, the high‐
90 est supported kernel protocol version is 7.26.
91 Users should be aware that the descriptions in this manual page
93 may be incomplete or incorrect for older or more recent protocol
94 versions.
95 The reply for this request has the following format:
97 struct fuse_init_out {
99 uint32_t major;
100 uint32_t minor;
101 uint32_t max_readahead; /* Since v7.6 */
102 uint32_t flags; /* Since v7.6; some flags bits
103 were introduced later */
104 uint16_t max_background; /* Since v7.13 */
105 uint16_t congestion_threshold; /* Since v7.13 */
106 uint32_t max_write; /* Since v7.5 */
107 uint32_t time_gran; /* Since v7.6 */
108 uint32_t unused[9];
109 };
110 If the major version supported by the kernel is larger than that
112 supported by the daemon, the reply shall consist of only
113 uint32_t major (following the usual header), indicating the
114 largest major version supported by the daemon. The kernel will
115 then issue a new FUSE_INIT request conforming to the older ver‐
116 sion. In the reverse case, the daemon should quietly fall back
117 to the kernel's major version.
118 The negotiated minor version is considered to be the minimum of
120 the minor versions provided by the daemon and the kernel and
121 both parties should use the protocol corresponding to said minor
122 version.
123 FUSE_GETATTR
125 struct fuse_getattr_in {
127 uint32_t getattr_flags;
128 uint32_t dummy;
129 uint64_t fh; /* Set only if
130 (getattr_flags & FUSE_GETATTR_FH)
131 };
132 The requested operation is to compute the attributes to be re‐
134 turned by stat(2) and similar operations for the given filesys‐
135 tem object. The object for which the attributes should be com‐
136 puted is indicated either by header->nodeid or, if the
137 FUSE_GETATTR_FH flag is set, by the file handle fh. The latter
138 case of operation is analogous to fstat(2).
139 For performance reasons, these attributes may be cached in the
141 kernel for a specified duration of time. While the cache time‐
142 out has not been exceeded, the attributes will be served from
143 the cache and will not cause additional FUSE_GETATTR requests.
144 The computed attributes and the requested cache timeout should
146 then be returned in the following structure:
147 struct fuse_attr_out {
149 /* Attribute cache duration (seconds + nanoseconds) */
150 uint64_t attr_valid;
151 uint32_t attr_valid_nsec;
152 uint32_t dummy;
153 struct fuse_attr {
154 uint64_t ino;
155 uint64_t size;
156 uint64_t blocks;
157 uint64_t atime;
158 uint64_t mtime;
159 uint64_t ctime;
160 uint32_t atimensec;
161 uint32_t mtimensec;
162 uint32_t ctimensec;
163 uint32_t mode;
164 uint32_t nlink;
165 uint32_t uid;
166 uint32_t gid;
167 uint32_t rdev;
168 uint32_t blksize;
169 uint32_t padding;
170 } attr;
171 };
172 FUSE_ACCESS
174 struct fuse_access_in {
176 uint32_t mask;
177 uint32_t padding;
178 };
179 If the default_permissions mount options is not used, this re‐
181 quest may be used for permissions checking. No reply data is
182 expected, but errors may be indicated as usual by setting the
183 error field in the reply header (in particular, access denied
184 errors may be indicated by returning -EACCES).
185 FUSE_OPEN and FUSE_OPENDIR
187 struct fuse_open_in {
188 uint32_t flags; /* The flags that were passed
189 to the open(2) */
190 uint32_t unused;
191 };
192 The requested operation is to open the node indicated by
194 header->nodeid. The exact semantics of what this means will de‐
195 pend on the filesystem being implemented. However, at the very
196 least the filesystem should validate that the requested flags
197 are valid for the indicated resource and then send a reply with
198 the following format:
199 struct fuse_open_out {
201 uint64_t fh;
202 uint32_t open_flags;
203 uint32_t padding;
204 };
205 The fh field is an opaque identifier that the kernel will use to
207 refer to this resource The open_flags field is a bit mask of any
208 number of the flags that indicate properties of this file handle
209 to the kernel:
210 FOPEN_DIRECT_IO Bypass page cache for this open file.
212 FOPEN_KEEP_CACHE Don't invalidate the data cache on open.
214 FOPEN_NONSEEKABLE The file is not seekable.
216 FUSE_READ and FUSE_READDIR
218 struct fuse_read_in {
220 uint64_t fh;
221 uint64_t offset;
222 uint32_t size;
223 uint32_t read_flags;
224 uint64_t lock_owner;
225 uint32_t flags;
226 uint32_t padding;
227 };
228 The requested action is to read up to size bytes of the file or
230 directory, starting at offset. The bytes should be returned di‐
231 rectly following the usual reply header.
232 FUSE_INTERRUPT
234 struct fuse_interrupt_in {
235 uint64_t unique;
236 };
237 The requested action is to cancel the pending operation indi‐
239 cated by unique. This request requires no response. However,
240 receipt of this message does not by itself cancel the indicated
241 operation. The kernel will still expect a reply to said opera‐
242 tion (e.g., an EINTR error or a short read). At most one
243 FUSE_INTERRUPT request will be issued for a given operation.
244 After issuing said operation, the kernel will wait uninterrupt‐
245 ibly for completion of the indicated request.
246 FUSE_LOOKUP
248 Directly following the header is a filename to be looked up in
249 the directory indicated by header->nodeid. The expected reply
250 is of the form:
251 struct fuse_entry_out {
253 uint64_t nodeid; /* Inode ID */
254 uint64_t generation; /* Inode generation */
255 uint64_t entry_valid;
256 uint64_t attr_valid;
257 uint32_t entry_valid_nsec;
258 uint32_t attr_valid_nsec;
259 struct fuse_attr attr;
260 };
261 The combination of nodeid and generation must be unique for the
263 filesystem's lifetime.
264 The interpretation of timeouts and attr is as for FUSE_GETATTR.
266 FUSE_FLUSH
268 struct fuse_flush_in {
269 uint64_t fh;
270 uint32_t unused;
271 uint32_t padding;
272 uint64_t lock_owner;
273 };
274 The requested action is to flush any pending changes to the in‐
276 dicated file handle. No reply data is expected. However, an
277 empty reply message still needs to be issued once the flush op‐
278 eration is complete.
279 FUSE_RELEASE and FUSE_RELEASEDIR
281 struct fuse_release_in {
282 uint64_t fh;
283 uint32_t flags;
284 uint32_t release_flags;
285 uint64_t lock_owner;
286 };
287 These are the converse of FUSE_OPEN and FUSE_OPENDIR respec‐
289 tively. The daemon may now free any resources associated with
290 the file handle fh as the kernel will no longer refer to it.
291 There is no reply data associated with this request, but a reply
292 still needs to be issued once the request has been completely
293 processed.
294 FUSE_STATFS
296 This operation implements statfs(2) for this filesystem. There
297 is no input data associated with this request. The expected re‐
298 ply data has the following structure:
299 struct fuse_kstatfs {
301 uint64_t blocks;
302 uint64_t bfree;
303 uint64_t bavail;
304 uint64_t files;
305 uint64_t ffree;
306 uint32_t bsize;
307 uint32_t namelen;
308 uint32_t frsize;
309 uint32_t padding;
310 uint32_t spare[6];
311 };
312 struct fuse_statfs_out {
314 struct fuse_kstatfs st;
315 };
316 For the interpretation of these fields, see statfs(2).
318
320 E2BIG Returned from read(2) operations when the kernel's request is
321 too large for the provided buffer and the request was FUSE_SETX‐
322 ATTR.
323 EINVAL Returned from write(2) if validation of the reply failed. Not
325 all mistakes in replies will be caught by this validation. How‐
326 ever, basic mistakes, such as short replies or an incorrect
327 unique value, are detected.
328 EIO Returned from read(2) operations when the kernel's request is
330 too large for the provided buffer.
331 Note: There are various ways in which incorrect use of these in‐
333 terfaces can cause operations on the provided filesystem's files
334 and directories to fail with EIO. Among the possible incorrect
335 uses are:
336 • changing mode & S_IFMT for an inode that has previously been
338 reported to the kernel; or
339 • giving replies to the kernel that are shorter than what the
341 kernel expected.
342 ENODEV Returned from read(2) and write(2) if the FUSE filesystem was
344 unmounted.
345 EPERM Returned from operations on a /dev/fuse file descriptor that has
347 not been mounted.
348
350 Linux.
351
353 The following messages are not yet documented in this manual page:
354 FUSE_BATCH_FORGET
356 FUSE_BMAP
357 FUSE_CREATE
358 FUSE_DESTROY
359 FUSE_FALLOCATE
360 FUSE_FORGET
361 FUSE_FSYNC
362 FUSE_FSYNCDIR
363 FUSE_GETLK
364 FUSE_GETXATTR
365 FUSE_IOCTL
366 FUSE_LINK
367 FUSE_LISTXATTR
368 FUSE_LSEEK
369 FUSE_MKDIR
370 FUSE_MKNOD
371 FUSE_NOTIFY_REPLY
372 FUSE_POLL
373 FUSE_READDIRPLUS
374 FUSE_READLINK
375 FUSE_REMOVEXATTR
376 FUSE_RENAME
377 FUSE_RENAME2
378 FUSE_RMDIR
379 FUSE_SETATTR
380 FUSE_SETLK
381 FUSE_SETLKW
382 FUSE_SYMLINK
383 FUSE_UNLINK
384 FUSE_WRITE
385
387 fusermount(1), mount.fuse(8)
388Linux man-pages 6.04 2023-03-30 fuse(4)