1FUSE(4)                    Linux Programmer's Manual                   FUSE(4)
2
3
4

NAME

6       fuse - Filesystem in Userspace (FUSE) device
7

SYNOPSIS

9       #include <linux/fuse.h>
10

DESCRIPTION

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
16       interface  itself.   Those  implementing  a FUSE filesystem may wish to
17       make use of a user-space library such as libfuse  that  abstracts  away
18       the low-level interface.
19
20       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
29   The basic protocol
30       Every message that is read by the daemon begins with a header described
31       by the following structure:
32
33           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
46       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
50       The  daemon  should  then  process the request and if applicable send a
51       reply (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
55           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
63       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
68   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
75       FUSE_INIT
76
77                  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
84              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
92              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
96              The reply for this request has the following format:
97
98                  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
111              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
119              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
124       FUSE_GETATTR
125
126                  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
133              The requested operation is  to  compute  the  attributes  to  be
134              returned  by  stat(2)  and similar operations for the given file
135              system object.  The object for which the  attributes  should  be
136              computed  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
140              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
145              The computed attributes and the requested cache  timeout  should
146              then be returned in the following structure:
147
148                  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
173       FUSE_ACCESS
174
175                  struct fuse_access_in {
176                      uint32_t mask;
177                      uint32_t padding;
178                  };
179
180              If  the  default_permissions  mount  options  is  not used, this
181              request 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
186       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
193              The  requested  operation  is  to  open  the  node  indicated by
194              header->nodeid.  The exact semantics of  what  this  means  will
195              depend  on  the  filesystem  being implemented.  However, at the
196              very least the filesystem should  validate  that  the  requested
197              flags are valid for the indicated resource and then send a reply
198              with the following format:
199
200                  struct fuse_open_out {
201                      uint64_t fh;
202                      uint32_t open_flags;
203                      uint32_t padding;
204                  };
205
206              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
211              FOPEN_DIRECT_IO   Bypass page cache for this open file.
212
213              FOPEN_KEEP_CACHE  Don't invalidate the data cache on open.
214
215              FOPEN_NONSEEKABLE The file is not seekable.
216
217       FUSE_READ and FUSE_READDIR
218
219                  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
229              The  requested action is to read up to size bytes of the file or
230              directory, starting at offset.  The  bytes  should  be  returned
231              directly following the usual reply header.
232
233       FUSE_INTERRUPT
234                  struct fuse_interrupt_in {
235                      uint64_t unique;
236                  };
237
238              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
247       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
252                  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
262              The combination of nodeid and generation must be unique for  the
263              filesystem's lifetime.
264
265              The interpretation of timeouts and attr is as for FUSE_GETATTR.
266
267       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
275              The  requested  action  is  to  flush any pending changes to the
276              indicated file handle.  No reply data is expected.  However,  an
277              empty  reply  message  still  needs  to be issued once the flush
278              operation is complete.
279
280       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
288              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
295       FUSE_STATFS
296              This  operation implements statfs(2) for this filesystem.  There
297              is no input data associated with  this  request.   The  expected
298              reply data has the following structure:
299
300                  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
313                  struct fuse_statfs_out {
314                      struct fuse_kstatfs st;
315                  };
316
317              For the interpretation of these fields, see statfs(2).
318

ERRORS

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
324       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
329       EIO    Returned from read(2) operations when the  kernel's  request  is
330              too large for the provided buffer.
331
332              Note:  There  are  various  ways in which incorrect use of these
333              interfaces can cause operations  on  the  provided  filesystem's
334              files  and  directories  to  fail  with EIO.  Among the possible
335              incorrect uses are:
336
337              *  changing mode & S_IFMT for an inode that has previously  been
338                 reported to the kernel; or
339
340              *  giving  replies  to the kernel that are shorter than what the
341                 kernel expected.
342
343       ENODEV Returned from read(2) and write(2) if the  FUSE  filesystem  was
344              unmounted.
345
346       EPERM  Returned from operations on a /dev/fuse file descriptor that has
347              not been mounted.
348

CONFORMING TO

350       The FUSE filesystem is Linux-specific.
351

NOTES

353       The following messages are not yet documented in this manual page:
354
355           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

SEE ALSO

387       fusermount(1), mount.fuse(8)
388

COLOPHON

390       This page is part of release 4.16 of the Linux  man-pages  project.   A
391       description  of  the project, information about reporting bugs, and the
392       latest    version    of    this    page,    can     be     found     at
393       https://www.kernel.org/doc/man-pages/.
394
395
396
397Linux                             2018-02-02                           FUSE(4)
Impressum