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 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 };
 456
 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)