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