Debian Codegraph @

upstream/debian-unstable/man4/fuse.4

raw
1 .\" Copyright 2016, Julia Computing, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH fuse 4 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 fuse \- Filesystem in Userspace (FUSE) device
9 .SH SYNOPSIS
10 .nf
11 .B #include <linux/fuse.h>
12 .fi
13 .SH DESCRIPTION
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
22 .I libfuse
23 that abstracts away the low-level interface.
24 .P
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
28 .BR read (2)
29 requests from that file descriptor and is expected to
30 .BR write (2)
31 back its replies.
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).
37 .\"
38 .SS The basic protocol
39 Every message that is read by the daemon begins with a header described by
40 the following structure:
41 .P
42 .in +4n
43 .EX
44 struct fuse_in_header {
45 uint32_t len; /* Total size 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
50 being operated on */
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 */
54 uint32_t padding;
55 };
56 .EE
57 .in
58 .P
59 The header is followed by a variable-size data portion
60 (which may be empty) specific to the requested operation
61 (the requested operation is indicated by
62 .IR opcode ).
63 .P
64 The daemon should then process the request
65 and
66 \[em]if applicable\[em]
67 send a reply
68 (almost all operations require a reply;
69 if they do not,
70 this is documented below),
71 by performing a
72 .BR write (2)
73 to the file descriptor.
74 All replies must start with the following header:
75 .P
76 .in +4n
77 .EX
78 struct fuse_out_header {
79 uint32_t len; /* Total size of data written to
80 the file descriptor */
81 int32_t error; /* Any error that occurred (0 if none) */
82 uint64_t unique; /* The value from the
83 corresponding request */
84 };
85 .EE
86 .in
87 .P
88 This header is also followed by (potentially empty) variable-sized
89 data depending on the executed request.
90 However, if the reply is an error reply (i.e.,
91 .I error
92 is set),
93 then no further payload data should be sent, independent of the request.
94 .\"
95 .SS Exchanged messages
96 This section should contain documentation for each of the messages
97 in the protocol.
98 This manual page is currently incomplete,
99 so not all messages are documented.
100 For each message, first the struct sent by the kernel is given,
101 followed by a description of the semantics of the message.
102 .TP
103 .B FUSE_INIT
104 .IP
105 .in +4n
106 .EX
107 struct fuse_init_in {
108 uint32_t major;
109 uint32_t minor;
110 uint32_t max_readahead; /* Since protocol v7.6 */
111 uint32_t flags; /* Since protocol v7.6 */
112 };
113 .EE
114 .in
115 .IP
116 This is the first request sent by the kernel to the daemon.
117 It is used to negotiate the protocol version and other filesystem parameters.
118 Note that the protocol version may affect the layout of any structure
119 in the protocol (including this structure).
120 The daemon must thus remember the negotiated version
121 and flags for each session.
122 As of the writing of this man page,
123 the highest supported kernel protocol version is
124 .IR 7.26 .
125 .IP
126 Users should be aware that the descriptions in this manual page
127 may be incomplete or incorrect for older or more recent protocol versions.
128 .IP
129 The reply for this request has the following format:
130 .IP
131 .in +4n
132 .EX
133 struct fuse_init_out {
134 uint32_t major;
135 uint32_t minor;
136 uint32_t max_readahead; /* Since v7.6 */
137 uint32_t flags; /* Since v7.6; some flags bits
138 were introduced later */
139 uint16_t max_background; /* Since v7.13 */
140 uint16_t congestion_threshold; /* Since v7.13 */
141 uint32_t max_write; /* Since v7.5 */
142 uint32_t time_gran; /* Since v7.6 */
143 uint32_t unused[9];
144 };
145 .EE
146 .in
147 .IP
148 If the major version supported by the kernel is larger than that supported
149 by the daemon, the reply shall consist of only
150 .I uint32_t major
151 (following the usual header),
152 indicating the largest major version supported by the daemon.
153 The kernel will then issue a new
154 .B FUSE_INIT
155 request conforming to the older version.
156 In the reverse case, the daemon should
157 quietly fall back to the kernel's major version.
158 .IP
159 The negotiated minor version is considered to be the minimum
160 of the minor versions provided by the daemon and the kernel and
161 both parties should use the protocol corresponding to said minor version.
162 .TP
163 .B FUSE_GETATTR
164 .IP
165 .in +4n
166 .EX
167 struct fuse_getattr_in {
168 uint32_t getattr_flags;
169 uint32_t dummy;
170 uint64_t fh; /* Set only if
171 (getattr_flags & FUSE_GETATTR_FH)
172 };
173 .EE
174 .in
175 .IP
176 The requested operation is to compute the attributes to be returned
177 by
178 .BR stat (2)
179 and similar operations for the given filesystem object.
180 The object for which the attributes should be computed is indicated
181 either by
182 .I header\->nodeid
183 or, if the
184 .B FUSE_GETATTR_FH
185 flag is set, by the file handle
186 .IR fh .
187 The latter case of operation is analogous to
188 .BR fstat (2).
189 .IP
190 For performance reasons, these attributes may be cached in the kernel for
191 a specified duration of time.
192 While the cache timeout has not been exceeded,
193 the attributes will be served from the cache and will not cause additional
194 .B FUSE_GETATTR
195 requests.
196 .IP
197 The computed attributes and the requested
198 cache timeout should then be returned in the following structure:
199 .IP
200 .in +4n
201 .EX
202 struct fuse_attr_out {
203 /* Attribute cache duration (seconds + nanoseconds) */
204 uint64_t attr_valid;
205 uint32_t attr_valid_nsec;
206 uint32_t dummy;
207 struct fuse_attr {
208 uint64_t ino;
209 uint64_t size;
210 uint64_t blocks;
211 uint64_t atime;
212 uint64_t mtime;
213 uint64_t ctime;
214 uint32_t atimensec;
215 uint32_t mtimensec;
216 uint32_t ctimensec;
217 uint32_t mode;
218 uint32_t nlink;
219 uint32_t uid;
220 uint32_t gid;
221 uint32_t rdev;
222 uint32_t blksize;
223 uint32_t padding;
224 } attr;
225 };
226 .EE
227 .in
228 .TP
229 .B FUSE_ACCESS
230 .IP
231 .in +4n
232 .EX
233 struct fuse_access_in {
234 uint32_t mask;
235 uint32_t padding;
236 };
237 .EE
238 .in
239 .IP
240 If the
241 .I default_permissions
242 mount options is not used, this request may be used for permissions checking.
243 No reply data is expected, but errors may be indicated
244 as usual by setting the
245 .I error
246 field in the reply header (in particular, access denied errors
247 may be indicated by returning
248 .BR \-EACCES ).
249 .TP
250 .B FUSE_OPEN
251 .TQ
252 .B FUSE_OPENDIR
253 .in +4n
254 .EX
255 struct fuse_open_in {
256 uint32_t flags; /* The flags that were passed
257 to the open(2) */
258 uint32_t unused;
259 };
260 .EE
261 .in
262 .IP
263 The requested operation is to open the node indicated by
264 .IR header\->nodeid .
265 The exact semantics of what this means will depend on the
266 filesystem being implemented.
267 However, at the very least the
268 filesystem should validate that the requested
269 .I flags
270 are valid for the indicated resource and then send a reply with the
271 following format:
272 .IP
273 .in +4n
274 .EX
275 struct fuse_open_out {
276 uint64_t fh;
277 uint32_t open_flags;
278 uint32_t padding;
279 };
280 .EE
281 .in
282 .IP
283 The
284 .I fh
285 field is an opaque identifier that the kernel will use to refer
286 to this resource
287 The
288 .I open_flags
289 field is a bit mask of any number of the flags
290 that indicate properties of this file handle to the kernel:
291 .RS 7
292 .TP 18
293 .B FOPEN_DIRECT_IO
294 Bypass page cache for this open file.
295 .TP
296 .B FOPEN_KEEP_CACHE
297 Don't invalidate the data cache on open.
298 .TP
299 .B FOPEN_NONSEEKABLE
300 The file is not seekable.
301 .RE
302 .TP
303 .B FUSE_READ
304 .TQ
305 .B FUSE_READDIR
306 .IP
307 .in +4n
308 .EX
309 struct fuse_read_in {
310 uint64_t fh;
311 uint64_t offset;
312 uint32_t size;
313 uint32_t read_flags;
314 uint64_t lock_owner;
315 uint32_t flags;
316 uint32_t padding;
317 };
318 .EE
319 .in
320 .IP
321 The requested action is to read up to
322 .I size
323 bytes of the file or directory, starting at
324 .IR offset .
325 The bytes should be returned directly following the usual reply header.
326 .TP
327 .B FUSE_INTERRUPT
328 .in +4n
329 .EX
330 struct fuse_interrupt_in {
331 uint64_t unique;
332 };
333 .EE
334 .in
335 .IP
336 The requested action is to cancel the pending operation indicated by
337 .IR unique .
338 This request requires no response.
339 However, receipt of this message does
340 not by itself cancel the indicated operation.
341 The kernel will still expect a reply to said operation (e.g., an
342 .I EINTR
343 error or a short read).
344 At most one
345 .B FUSE_INTERRUPT
346 request will be issued for a given operation.
347 After issuing said operation,
348 the kernel will wait uninterruptibly for completion of the indicated request.
349 .TP
350 .B FUSE_LOOKUP
351 Directly following the header is a filename to be looked up in the directory
352 indicated by
353 .IR header\->nodeid .
354 The expected reply is of the form:
355 .IP
356 .in +4n
357 .EX
358 struct fuse_entry_out {
359 uint64_t nodeid; /* Inode ID */
360 uint64_t generation; /* Inode generation */
361 uint64_t entry_valid;
362 uint64_t attr_valid;
363 uint32_t entry_valid_nsec;
364 uint32_t attr_valid_nsec;
365 struct fuse_attr attr;
366 };
367 .EE
368 .in
369 .IP
370 The combination of
371 .I nodeid
372 and
373 .I generation
374 must be unique for the filesystem's lifetime.
375 .IP
376 The interpretation of timeouts and
377 .I attr
378 is as for
379 .BR FUSE_GETATTR .
380 .TP
381 .B FUSE_FLUSH
382 .in +4n
383 .EX
384 struct fuse_flush_in {
385 uint64_t fh;
386 uint32_t unused;
387 uint32_t padding;
388 uint64_t lock_owner;
389 };
390 .EE
391 .in
392 .IP
393 The requested action is to flush any pending changes to the indicated
394 file handle.
395 No reply data is expected.
396 However, an empty reply message
397 still needs to be issued once the flush operation is complete.
398 .TP
399 .B FUSE_RELEASE
400 .TQ
401 .B FUSE_RELEASEDIR
402 .in +4n
403 .EX
404 struct fuse_release_in {
405 uint64_t fh;
406 uint32_t flags;
407 uint32_t release_flags;
408 uint64_t lock_owner;
409 };
410 .EE
411 .in
412 .IP
413 These are the converse of
414 .B FUSE_OPEN
415 and
416 .B FUSE_OPENDIR
417 respectively.
418 The daemon may now free any resources associated with the
419 file handle
420 .I fh
421 as the kernel will no longer refer to it.
422 There is no reply data associated with this request,
423 but a reply still needs to be issued once the request has
424 been completely processed.
425 .TP
426 .B FUSE_STATFS
427 This operation implements
428 .BR statfs (2)
429 for this filesystem.
430 There is no input data associated with this request.
431 The expected reply data has the following structure:
432 .IP
433 .in +4n
434 .EX
435 struct fuse_kstatfs {
436 uint64_t blocks;
437 uint64_t bfree;
438 uint64_t bavail;
439 uint64_t files;
440 uint64_t ffree;
441 uint32_t bsize;
442 uint32_t namelen;
443 uint32_t frsize;
444 uint32_t padding;
445 uint32_t spare[6];
446 };
447 \&
448 struct fuse_statfs_out {
449 struct fuse_kstatfs st;
450 };
451 .EE
452 .in
453 .IP
454 For the interpretation of these fields, see
455 .BR statfs (2).
456 .SH ERRORS
457 .TP
458 .B E2BIG
459 Returned from
460 .BR read (2)
461 operations when the kernel's request is too large for the provided buffer
462 and the request was
463 .BR FUSE_SETXATTR .
464 .TP
465 .B EINVAL
466 Returned from
467 .BR write (2)
468 if validation of the reply failed.
469 Not all mistakes in replies will be caught by this validation.
470 However, basic mistakes, such as short replies or an incorrect
471 .I unique
472 value, are detected.
473 .TP
474 .B EIO
475 Returned from
476 .BR read (2)
477 operations when the kernel's request is too large for the provided buffer.
478 .IP
479 .IR Note :
480 There are various ways in which incorrect use of these interfaces can cause
481 operations on the provided filesystem's files and directories to fail with
482 .BR EIO .
483 Among the possible incorrect uses are:
484 .RS
485 .IP \[bu] 3
486 changing
487 .I mode & S_IFMT
488 for an inode that has previously been reported to the kernel;
489 or
490 .IP \[bu]
491 giving replies to the kernel that are shorter than what the kernel expected.
492 .RE
493 .TP
494 .B ENODEV
495 Returned from
496 .BR read (2)
497 and
498 .BR write (2)
499 if the FUSE filesystem was unmounted.
500 .TP
501 .B EPERM
502 Returned from operations on a
503 .I /dev/fuse
504 file descriptor that has not been mounted.
505 .SH STANDARDS
506 Linux.
507 .SH NOTES
508 The following messages are not yet documented in this manual page:
509 .P
510 .\" FIXME: Document the following.
511 .in +4n
512 .EX
513 .B FUSE_BATCH_FORGET
514 .B FUSE_BMAP
515 .B FUSE_CREATE
516 .B FUSE_DESTROY
517 .B FUSE_FALLOCATE
518 .B FUSE_FORGET
519 .B FUSE_FSYNC
520 .B FUSE_FSYNCDIR
521 .B FUSE_GETLK
522 .B FUSE_GETXATTR
523 .B FUSE_IOCTL
524 .B FUSE_LINK
525 .B FUSE_LISTXATTR
526 .B FUSE_LSEEK
527 .B FUSE_MKDIR
528 .B FUSE_MKNOD
529 .B FUSE_NOTIFY_REPLY
530 .B FUSE_POLL
531 .B FUSE_READDIRPLUS
532 .B FUSE_READLINK
533 .B FUSE_REMOVEXATTR
534 .B FUSE_RENAME
535 .B FUSE_RENAME2
536 .B FUSE_RMDIR
537 .B FUSE_SETATTR
538 .B FUSE_SETLK
539 .B FUSE_SETLKW
540 .B FUSE_SYMLINK
541 .B FUSE_UNLINK
542 .B FUSE_WRITE
543 .EE
544 .in
545 .SH SEE ALSO
546 .BR fusermount (1),
547 .BR mount.fuse (8)