Debian Codegraph @

upstream/fedora-44/man4/fuse.4

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