man4/fuse.4

   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 (date) "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  42 .in +4n
  43 .EX
  44 struct fuse_in_header {
  45     uint32_t len;       /* Total length 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 .PP
  59 The header is followed by a variable-length data portion
  60 (which may be empty) specific to the requested operation
  61 (the requested operation is indicated by
  62 .IR opcode ).
  63 .PP
  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 .PP
  71 .in +4n
  72 .EX
  73 struct fuse_out_header {
  74     uint32_t len;       /* Total length 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 .PP
  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 .BR FUSE_OPEN " and " FUSE_OPENDIR
 246 .in +4n
 247 .EX
 248 struct fuse_open_in {
 249     uint32_t flags;     /* The flags that were passed
 250                            to the open(2) */
 251     uint32_t unused;
 252 };
 253 .EE
 254 .in
 255 .IP
 256 The requested operation is to open the node indicated by
 257 .IR header\->nodeid .
 258 The exact semantics of what this means will depend on the
 259 filesystem being implemented.
 260 However, at the very least the
 261 filesystem should validate that the requested
 262 .I flags
 263 are valid for the indicated resource and then send a reply with the
 264 following format:
 265 .IP
 266 .in +4n
 267 .EX
 268 struct fuse_open_out {
 269     uint64_t fh;
 270     uint32_t open_flags;
 271     uint32_t padding;
 272 };
 273 .EE
 274 .in
 275 .IP
 276 The
 277 .I fh
 278 field is an opaque identifier that the kernel will use to refer
 279 to this resource
 280 The
 281 .I open_flags
 282 field is a bit mask of any number of the flags
 283 that indicate properties of this file handle to the kernel:
 284 .RS 7
 285 .TP 18
 286 .B FOPEN_DIRECT_IO
 287 Bypass page cache for this open file.
 288 .TP
 289 .B FOPEN_KEEP_CACHE
 290 Don't invalidate the data cache on open.
 291 .TP
 292 .B FOPEN_NONSEEKABLE
 293 The file is not seekable.
 294 .RE
 295 .TP
 296 .BR FUSE_READ " and " FUSE_READDIR
 297 .IP
 298 .in +4n
 299 .EX
 300 struct fuse_read_in {
 301     uint64_t fh;
 302     uint64_t offset;
 303     uint32_t size;
 304     uint32_t read_flags;
 305     uint64_t lock_owner;
 306     uint32_t flags;
 307     uint32_t padding;
 308 };
 309 .EE
 310 .in
 311 .IP
 312 The requested action is to read up to
 313 .I size
 314 bytes of the file or directory, starting at
 315 .IR offset .
 316 The bytes should be returned directly following the usual reply header.
 317 .TP
 318 .B FUSE_INTERRUPT
 319 .in +4n
 320 .EX
 321 struct fuse_interrupt_in {
 322     uint64_t unique;
 323 };
 324 .EE
 325 .in
 326 .IP
 327 The requested action is to cancel the pending operation indicated by
 328 .IR unique .
 329 This request requires no response.
 330 However, receipt of this message does
 331 not by itself cancel the indicated operation.
 332 The kernel will still expect a reply to said operation (e.g., an
 333 .I EINTR
 334 error or a short read).
 335 At most one
 336 .B FUSE_INTERRUPT
 337 request will be issued for a given operation.
 338 After issuing said operation,
 339 the kernel will wait uninterruptibly for completion of the indicated request.
 340 .TP
 341 .B FUSE_LOOKUP
 342 Directly following the header is a filename to be looked up in the directory
 343 indicated by
 344 .IR header\->nodeid .
 345 The expected reply is of the form:
 346 .IP
 347 .in +4n
 348 .EX
 349 struct fuse_entry_out {
 350     uint64_t nodeid;            /* Inode ID */
 351     uint64_t generation;        /* Inode generation */
 352     uint64_t entry_valid;
 353     uint64_t attr_valid;
 354     uint32_t entry_valid_nsec;
 355     uint32_t attr_valid_nsec;
 356     struct fuse_attr attr;
 357 };
 358 .EE
 359 .in
 360 .IP
 361 The combination of
 362 .I nodeid
 363 and
 364 .I generation
 365 must be unique for the filesystem's lifetime.
 366 .IP
 367 The interpretation of timeouts and
 368 .I attr
 369 is as for
 370 .BR FUSE_GETATTR .
 371 .TP
 372 .B FUSE_FLUSH
 373 .in +4n
 374 .EX
 375 struct fuse_flush_in {
 376     uint64_t fh;
 377     uint32_t unused;
 378     uint32_t padding;
 379     uint64_t lock_owner;
 380 };
 381 .EE
 382 .in
 383 .IP
 384 The requested action is to flush any pending changes to the indicated
 385 file handle.
 386 No reply data is expected.
 387 However, an empty reply message
 388 still needs to be issued once the flush operation is complete.
 389 .TP
 390 .BR FUSE_RELEASE " and " FUSE_RELEASEDIR
 391 .in +4n
 392 .EX
 393 struct fuse_release_in {
 394     uint64_t fh;
 395     uint32_t flags;
 396     uint32_t release_flags;
 397     uint64_t lock_owner;
 398 };
 399 .EE
 400 .in
 401 .IP
 402 These are the converse of
 403 .B FUSE_OPEN
 404 and
 405 .B FUSE_OPENDIR
 406 respectively.
 407 The daemon may now free any resources associated with the
 408 file handle
 409 .I fh
 410 as the kernel will no longer refer to it.
 411 There is no reply data associated with this request,
 412 but a reply still needs to be issued once the request has
 413 been completely processed.
 414 .TP
 415 .B FUSE_STATFS
 416 This operation implements
 417 .BR statfs (2)
 418 for this filesystem.
 419 There is no input data associated with this request.
 420 The expected reply data has the following structure:
 421 .IP
 422 .in +4n
 423 .EX
 424 struct fuse_kstatfs {
 425     uint64_t blocks;
 426     uint64_t bfree;
 427     uint64_t bavail;
 428     uint64_t files;
 429     uint64_t ffree;
 430     uint32_t bsize;
 431     uint32_t namelen;
 432     uint32_t frsize;
 433     uint32_t padding;
 434     uint32_t spare[6];
 435 };
 436 \&
 437 struct fuse_statfs_out {
 438     struct fuse_kstatfs st;
 439 };
 440 .EE
 441 .in
 442 .IP
 443 For the interpretation of these fields, see
 444 .BR statfs (2).
 445 .SH ERRORS
 446 .TP
 447 .B E2BIG
 448 Returned from
 449 .BR read (2)
 450 operations when the kernel's request is too large for the provided buffer
 451 and the request was
 452 .BR FUSE_SETXATTR .
 453 .TP
 454 .B EINVAL
 455 Returned from
 456 .BR write (2)
 457 if validation of the reply failed.
 458 Not all mistakes in replies will be caught by this validation.
 459 However, basic mistakes, such as short replies or an incorrect
 460 .I unique
 461 value, are detected.
 462 .TP
 463 .B EIO
 464 Returned from
 465 .BR read (2)
 466 operations when the kernel's request is too large for the provided buffer.
 467 .IP
 468 .IR Note :
 469 There are various ways in which incorrect use of these interfaces can cause
 470 operations on the provided filesystem's files and directories to fail with
 471 .BR EIO .
 472 Among the possible incorrect uses are:
 473 .RS
 474 .IP \[bu] 3
 475 changing
 476 .I mode & S_IFMT
 477 for an inode that has previously been reported to the kernel; or
 478 .IP \[bu]
 479 giving replies to the kernel that are shorter than what the kernel expected.
 480 .RE
 481 .TP
 482 .B ENODEV
 483 Returned from
 484 .BR read (2)
 485 and
 486 .BR write (2)
 487 if the FUSE filesystem was unmounted.
 488 .TP
 489 .B EPERM
 490 Returned from operations on a
 491 .I /dev/fuse
 492 file descriptor that has not been mounted.
 493 .SH STANDARDS
 494 Linux.
 495 .SH NOTES
 496 The following messages are not yet documented in this manual page:
 497 .PP
 498 .\" FIXME: Document the following.
 499 .in +4n
 500 .EX
 501 .B FUSE_BATCH_FORGET
 502 .B FUSE_BMAP
 503 .B FUSE_CREATE
 504 .B FUSE_DESTROY
 505 .B FUSE_FALLOCATE
 506 .B FUSE_FORGET
 507 .B FUSE_FSYNC
 508 .B FUSE_FSYNCDIR
 509 .B FUSE_GETLK
 510 .B FUSE_GETXATTR
 511 .B FUSE_IOCTL
 512 .B FUSE_LINK
 513 .B FUSE_LISTXATTR
 514 .B FUSE_LSEEK
 515 .B FUSE_MKDIR
 516 .B FUSE_MKNOD
 517 .B FUSE_NOTIFY_REPLY
 518 .B FUSE_POLL
 519 .B FUSE_READDIRPLUS
 520 .B FUSE_READLINK
 521 .B FUSE_REMOVEXATTR
 522 .B FUSE_RENAME
 523 .B FUSE_RENAME2
 524 .B FUSE_RMDIR
 525 .B FUSE_SETATTR
 526 .B FUSE_SETLK
 527 .B FUSE_SETLKW
 528 .B FUSE_SYMLINK
 529 .B FUSE_UNLINK
 530 .B FUSE_WRITE
 531 .EE
 532 .in
 533 .SH SEE ALSO
 534 .BR fusermount (1),
 535 .BR mount.fuse (8)