1 .\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer
2 .\" Description based on include/uapi/fuse.h and code in fs/fuse
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH FUSE 4 2016-12-10 "Linux" "Linux Programmer's Manual"
28 fuse \- Filesystem in Userspace (FUSE) device
31 .B #include <linux/fuse.h>
35 This device is the primary interface between the FUSE filesystem driver
36 and a user-space process wishing to provide the filesystem (referred to
37 in the rest of this manual page as the
38 .IR "filesystem daemon" ).
39 This manual page is intended for those
40 interested in understanding the kernel interface itself.
41 Those implementing a FUSE filesystem may wish to make use of
42 a user-space library such as
44 that abstracts away the low-level interface.
46 At its core, FUSE is a simple client-server protocol, in which the Linux
47 kernel is the client and the daemon is the server.
48 After obtaining a file descriptor for this device, the daemon may
50 requests from that file descriptor and is expected to
53 It is important to note that a file descriptor is
54 associated with a unique FUSE filesystem.
55 In particular, opening a second copy of this device,
56 will not allow access to resources created
57 through the first file descriptor (and vice versa).
59 .SS The basic protocol
60 Every message that is read by the daemon begins with a header described by
61 the following structure:
65 struct fuse_in_header {
66 uint32_t len; /* Total length of the data,
67 including this header */
68 uint32_t opcode; /* The kind of operation (see below) */
69 uint64_t unique; /* A unique identifier for this request */
70 uint64_t nodeid; /* ID of the filesystem object
72 uint32_t uid; /* UID of the requesting process */
73 uint32_t gid; /* GID of the requesting process */
74 uint32_t pid; /* PID of the requesting process */
80 The header is followed by a variable-length data portion
81 (which may be empty) specific to the requested operation
82 (the requested operation is indicated by
85 The daemon should then process the request and if applicable send
86 a reply (almost all operations require a reply; if they do not,
87 this is documented below), by performing a
89 to the file descriptor.
90 All replies must start with the following header:
94 struct fuse_out_header {
95 uint32_t len; /* Total length of data written to
96 the file descriptor */
97 int32_t error; /* Any error that occurred (0 if none) */
98 uint64_t unique; /* The value from the
99 corresponding request */
104 This header is also followed by (potentially empty) variable-sized
105 data depending on the executed request.
106 However, if the reply is an error reply (i.e.,
109 then no further payload data should be sent, independent of the request.
111 .SS Exchanged messages
112 This section should contain documentation for each of the messages
114 This manual page is currently incomplete,
115 so not all messages are documented.
116 For each message, first the struct sent by the kernel is given,
117 followed by a description of the semantics of the message.
123 struct fuse_init_in {
126 uint32_t max_readahead; /* Since protocol v7.6 */
127 uint32_t flags; /* Since protocol v7.6 */
132 This is the first request sent by the kernel to the daemon.
133 It is used to negotiate the protocol version and other filesystem parameters.
134 Note that the protocol version may affect the layout of any structure
135 in the protocol (including this structure).
136 The daemon must thus remember the negotiated version
137 and flags for each session.
138 As of the writing of this man page,
139 the highest supported kernel protocol version is
142 Users should be aware that the descriptions in this manual page
143 may be incomplete or incorrect for older or more recent protocol versions.
145 The reply for this request has the following format:
149 struct fuse_init_out {
152 uint32_t max_readahead; /* Since v7.6 */
153 uint32_t flags; /* Since v7.6; some flags bits
154 were introduced later */
155 uint16_t max_background; /* Since v7.13 */
156 uint16_t congestion_threshold; /* Since v7.13 */
157 uint32_t max_write; /* Since v7.5 */
158 uint32_t time_gran; /* Since v7.6 */
164 If the major version supported by the kernel is larger than that supported
165 by the daemon, the reply shall consist of only
167 (following the usual header),
168 indicating the largest major version supported by the daemon.
169 The kernel will then issue a new
171 request conforming to the older version.
172 In the reverse case, the daemon should
173 quietly fall back to the kernel's major version.
175 The negotiated minor version is considered to be the minimum
176 of the minor versions provided by the daemon and the kernel and
177 both parties should use the protocol corresponding to said minor version.
183 struct fuse_getattr_in {
184 uint32_t getattr_flags;
186 uint64_t fh; /* Set only if
187 (getattr_flags & FUSE_GETATTR_FH)
192 The requested operation is to compute the attributes to be returned
195 and similar operations for the given file system object.
196 The object for which the attributes should be computed is indicated
201 flag is set, by the file handle
203 The latter case of operation is analogous to
206 For performance reasons, these attributes may be cached in the kernel for
207 a specified duration of time.
208 While the cache timeout has not been exceeded,
209 the attributes will be served from the cache and will not cause additional
213 The computed attributes and the requested
214 cache timeout should then be returned in the following structure:
218 struct fuse_attr_out {
219 /* Attribute cache duration (seconds + nanoseconds) */
221 uint32_t attr_valid_nsec;
250 struct fuse_access_in {
258 .I default_permissions
259 mount options is not used, this request may be used for permissions checking.
260 No reply data is expected, but errors may be indicated
261 as usual by setting the
263 field in the reply header (in particular, access denied errors
264 may be indicated by returning
267 .BR FUSE_OPEN " and " FUSE_OPENDIR
270 struct fuse_open_in {
271 uint32_t flags; /* The flags that were passed
278 The requested operation is to open the node indicated by
279 .IR header\->nodeid .
280 The exact semantics of what this means will depend on the
281 filesystem being implemented.
282 However, at the very least the
283 filesystem should validate that the requested
285 are valid for the indicated resource and then send a reply with the
291 struct fuse_open_out {
302 field is an opaque identifier that the kernel will use to refer
306 field is a bit mask of any number of the flags
307 that indicate properties of this file handle to the kernel:
311 Bypass page cache for this open file.
314 Don't invalidate the data cache on open.
316 .BR FOPEN_NONSEEKABLE
317 The file is not seekable.
320 .BR FUSE_READ " and " FUSE_READDIR
324 struct fuse_read_in {
337 The requested action is to read up to
339 bytes of the file or directory, starting at
341 The bytes should be returned directly following the usual reply header.
346 struct fuse_interrupt_in {
352 The requested action is to cancel the pending operation indicated by
354 This request requires no response.
355 However, receipt of this message does
356 not by itself cancel the indicated operation.
357 The kernel will still expect a reply to said operation (e.g., an
359 error or a short read).
362 request will be issued for a given operation.
363 After issuing said operation,
364 the kernel will wait uninterruptibly for completion of the indicated request.
367 Directly following the header is a filename to be looked up in the directory
369 .IR header\->nodeid .
370 The expected reply is of the form:
374 struct fuse_entry_out {
375 uint64_t nodeid; /* Inode ID */
376 uint64_t generation; /* Inode generation */
377 uint64_t entry_valid;
379 uint32_t entry_valid_nsec;
380 uint32_t attr_valid_nsec;
381 struct fuse_attr attr;
390 must be unique for the filesystem's lifetime.
392 The interpretation of timeouts and
400 struct fuse_flush_in {
409 The requested action is to flush any pending changes to the indicated
411 No reply data is expected.
412 However, an empty reply message
413 still needs to be issued once the flush operation is complete.
415 .BR FUSE_RELEASE " and " FUSE_RELEASEDIR
418 struct fuse_release_in {
421 uint32_t release_flags;
427 These are the converse of
432 The daemon may now free any resources associated with the
435 as the kernel will no longer refer to it.
436 There is no reply data associated with this request,
437 but a reply still needs to be issued once the request has
438 been completely processed.
441 This operation implements
444 There is no input data associated with this request.
445 The expected reply data has the following structure:
449 struct fuse_kstatfs {
462 struct fuse_statfs_out {
463 struct fuse_kstatfs st;
468 For the interpretation of these fields, see
473 Returned from operations on a
475 file descriptor that has not been mounted.
480 operations when the kernel's request is too large for the provided buffer.
483 There are various ways in which incorrect use of these interfaces can cause
484 operations on the provided filesystem's files and directories to fail with
486 Among the possible incorrect uses are:
491 for an inode that has previously been reported to the kernel; or
493 giving replies to the kernel that are shorter than what the kernel expected.
499 if validation of the reply failed.
500 Not all mistakes in replies will be caught by this validation.
501 However, basic mistakes, such as short replies or an incorrect
508 operations when the kernel's request is too large for the provided buffer
517 if the FUSE filesystem was unmounted.
519 The FUSE filesystem is Linux-specific.
521 The following messages are not yet documented in this manual page:
522 .\" FIXME: Document the following.
525 .BR FUSE_BATCH_FORGET
541 .BR FUSE_NOTIFY_REPLY