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