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 2016-12-10 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 /dev/fuse \- Filesystem in Userspace (FUSE) device
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <linux/fuse.h>
  32 .nf
  33 .SH DESCRIPTION
  34
  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
  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
  63 .in +4n
  64 .nf
  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 .fi
  78 .in
  79
  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
  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
  92 .in +4n
  93 .nf
  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 .fi
 102 .in
 103
 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 " ( 25 )"
 120
 121 .in +4n
 122 .nf
 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 .fi
 130 .in
 131
 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
 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
 145 The reply for this request has the following format:
 146
 147 .in +4n
 148 .nf
 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 .fi
 162 .in
 163
 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
 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 " ( 3 )"
 180 .\" FIXME It looks like this is for implementing a stat(2) type of
 181 .\" operation. There needs to be a sentence here describing what
 182 .\" this option does.
 183
 184 .in +4n
 185 .nf
 186 struct fuse_getattr_in {
 187     uint32_t getattr_flags;
 188     uint32_t dummy;
 189     uint64_t fh;      /* Set only if
 190                          (getattr_flags & FUSE_GETATTR_FH)
 191 };
 192 .fi
 193 .in
 194
 195 As usual, the filesystem object operated on is indicated by
 196 .IR header\->nodeid .
 197 The daemon should compute the attributes
 198 of this object and reply with the following message:
 199 .in +4n
 200
 201 .nf
 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 };
 220
 221 struct fuse_attr_out {
 222     /* Attribute cache duration (seconds + nanoseconds) */
 223     uint64_t attr_valid;
 224     uint32_t attr_valid_nsec;
 225     uint32_t dummy;
 226     struct fuse_attr attr;
 227 };
 228 .fi
 229 .in
 230
 231 The fields of
 232 .I struct fuse_attr
 233 describe the attributes of the required file.
 234 For the interpretation of these fields, see
 235 .BR stat (2).
 236 .TP
 237 .BR FUSE_ACCESS " ( 34 )"
 238
 239 .in +4n
 240 .nf
 241 struct fuse_access_in {
 242     uint32_t mask;
 243     uint32_t padding;
 244 };
 245 .fi
 246 .in
 247
 248 If the
 249 .I default_permissions
 250 mount options is not used, this request may be used for permissions checking.
 251 No reply data is expected, but errors may be indicated
 252 as usual in the reply header (in particular, access denied errors
 253 may be indicated, by setting such field to
 254 .\" FIXME What does "such field" mean? The 'error' field?
 255 .BR \-EACCES ).
 256 .TP
 257 .BR FUSE_OPEN " ( 14 ) and " FUSE_OPENDIR " ( 34 )"
 258 .in +4n
 259 .nf
 260 struct fuse_open_in {
 261     uint32_t flags;     /* The flags that were passed
 262                            to the open(2) */
 263     uint32_t unused;
 264 };
 265 .fi
 266 .in
 267
 268 The requested operation is to open the node indicated by
 269 .IR header\->nodeid .
 270 The exact semantics of what this means will depend on the
 271 filesystem being implemented.
 272 However, at the very least the
 273 filesystem should validate that the requested
 274 .I flags
 275 are valid for the indicated resource and then send a reply with the
 276 following format:
 277
 278 .in +4n
 279 .nf
 280
 281 struct fuse_open_out {
 282     uint64_t fh;
 283     uint32_t open_flags;
 284     uint32_t padding;
 285 };
 286
 287 .fi
 288 .in
 289
 290 The
 291 .I fh
 292 field is an opaque identifier that the kernel will use to refer
 293 to this resource
 294 The
 295 .I open_flags
 296 field is a bit mask of any number of the flags
 297 that indicate properties of this file handle to the kernel:
 298 .RS 7
 299 .TP 18
 300 .BR FOPEN_DIRECT_IO
 301 Bypass page cache for this open file.
 302 .TP
 303 .BR FOPEN_KEEP_CACHE
 304 Don't invalidate the data cache on open.
 305 .TP
 306 .BR FOPEN_NONSEEKABLE
 307 The file is not seekable.
 308 .RE
 309 .TP
 310 .BR FUSE_READ " ( 15 ) and " FUSE_READDIR " ( 28 )"
 311 .in +4n
 312 .nf
 313
 314 struct fuse_read_in {
 315     uint64_t fh;
 316     uint64_t offset;
 317     uint32_t size;
 318     uint32_t read_flags;
 319     uint64_t lock_owner;
 320     uint32_t flags;
 321     uint32_t padding;
 322 };
 323
 324 .fi
 325 .in
 326
 327 The requested action is to read up to
 328 .I size
 329 bytes of the file or directory, starting at
 330 .IR offset .
 331 .\" FIXME
 332 .\" In the following, what are "out header" and "out structure"?
 333 The bytes should be returned directly following the out header,
 334 with no further special out structure.
 335 .TP
 336 .BR FUSE_INTERRUPT " ( 36 )"
 337 .in +4n
 338 .nf
 339 struct fuse_interrupt_in {
 340     uint64_t unique;
 341 };
 342 .fi
 343 .in
 344
 345 The requested action is to cancel the pending operation indicated by
 346 .IR unique .
 347 This request requires no response.
 348 However, receipt of this message does
 349 not by itself cancel the indicated operation.
 350 The kernel will still expect a reply to said operation (e.g., an
 351 .I EINTR
 352 error or a short read).
 353 At most one
 354 .B FUSE_INTERRUPT
 355 request will be issued for a given operation.
 356 After issuing said operation,
 357 the kernel will wait uninterruptibly for completion of the indicated request.
 358 .TP
 359 .BR FUSE_LOOKUP " ( 1 )"
 360 Directly following the header is a filename to be looked up in the directory
 361 indicated by
 362 .IR header\->nodeid .
 363 The expected reply is of the form:
 364
 365 .in +4n
 366 .nf
 367 struct fuse_entry_out {
 368     uint64_t nodeid;            /* Inode ID */
 369     uint64_t generation;        /* Inode generation */
 370     uint64_t entry_valid;
 371     uint64_t attr_valid;
 372     uint32_t entry_valid_nsec;
 373     uint32_t attr_valid_nsec;
 374     struct fuse_attr attr;
 375 };
 376 .fi
 377 .in
 378
 379 The combination of
 380 .I nodeid
 381 and
 382 .I generation
 383 must be unique for the filesystem's lifetime.
 384
 385 The interpretation of timeouts and
 386 .I attr
 387 is as for
 388 .BR FUSE_GETATTR .
 389 .TP
 390 .BR FUSE_FLUSH " ( 36 )"
 391 .in +4n
 392 .nf
 393 struct fuse_flush_in {
 394     uint64_t fh;
 395     uint32_t unused;
 396     uint32_t padding;
 397     uint64_t lock_owner;
 398 };
 399 .fi
 400 .in
 401
 402 The requested action is to flush any pending changes to the indicated
 403 file handle.
 404 No reply data is expected.
 405 However, an empty reply message
 406 still needs to be issued once the flush operation is complete.
 407 .TP
 408 .BR FUSE_RELEASE " ( 18 ) and " FUSE_RELEASEDIR " ( 29 )"
 409 .in +4n
 410 .nf
 411 struct fuse_release_in {
 412     uint64_t fh;
 413     uint32_t flags;
 414     uint32_t release_flags;
 415     uint64_t lock_owner;
 416 };
 417 .fi
 418 .in
 419
 420 These are the converse of
 421 .BR FUSE_OPEN
 422 and
 423 .BR FUSE_OPENDIR
 424 respectively.
 425 The daemon may now free any resources associated with the
 426 file handle
 427 .I fh
 428 as the kernel will no longer refer to it.
 429 There is no reply data associated with this request,
 430 but a reply still needs to be issued once the request has
 431 been completely processed.
 432 .TP
 433 .BR FUSE_STATFS " ( 17 )"
 434 This operation implements
 435 .BR statfs (2)
 436 for this filesystem.
 437 There is no input data associated with this request.
 438 The expected reply data has the following structure:
 439
 440 .in +4n
 441 .nf
 442 struct fuse_kstatfs {
 443     uint64_t blocks;
 444     uint64_t bfree;
 445     uint64_t bavail;
 446     uint64_t files;
 447     uint64_t ffree;
 448     uint32_t bsize;
 449     uint32_t namelen;
 450     uint32_t frsize;
 451     uint32_t padding;
 452     uint32_t spare[6];
 453 };
 454
 455 struct fuse_statfs_out {
 456     struct fuse_kstatfs st;
 457 };
 458 .fi
 459 .in
 460
 461 For the interpretation of these fields, see
 462 .BR statfs (2).
 463 .SH ERRORS
 464 .TP
 465 .B EPERM
 466 Returned from operations on a
 467 .I /dev/fuse
 468 file descriptor that has not been mounted.
 469 .TP
 470 .B EIO
 471 Returned from
 472 .BR read (2)
 473 operations when the kernel's request is too large for the provided buffer.
 474
 475 .IR Note :
 476 There are various ways in which incorrect use of these interfaces can cause
 477 operations on the provided filesystem's files and directories to fail with
 478 .BR EIO .
 479 Among the possible incorrect uses are
 480 .IP * 3
 481 changing
 482 .I mode & S_IFMT
 483 for an inode that has previously been reported to the kernel; or
 484 .IP *
 485 giving replies to the kernel that are shorter than what the kernel expected.
 486 .TP
 487 .B EINVAL
 488 Returned from
 489 .BR write (2)
 490 if validation of the reply failed.
 491 Not all mistakes in replies will be caught by this validation.
 492 However, basic mistakes, such as short replies or an incorrect
 493 .I unique
 494 value, are detected.
 495 .TP
 496 .B E2BIG
 497 Returned from
 498 .BR read (2)
 499 operations when the kernel's request is too large for the provided buffer
 500 and the request was
 501 .BR FUSE_SETXATTR .
 502 .TP
 503 .B ENODEV
 504 Returned from
 505 .BR read (2)
 506 and
 507 .BR write (2)
 508 if the FUSE filesystem was unmounted.
 509 .SH CONFORMING TO
 510 The FUSE filesystem is Linux-specific.
 511 .SH SEE ALSO
 512 .BR fusermount (1),
 513 .BR mount.fuse (8)