| 1 |
.\" Copyright 2016, Julia Computing, Inc. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH fuse 4 2026-02-08 "Linux man-pages 6.18" |
| 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 |
.P |
| 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 |
.P |
| 42 |
.in +4n |
| 43 |
.EX |
| 44 |
struct fuse_in_header { |
| 45 |
uint32_t len; /* Total size 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 |
.P |
| 59 |
The header is followed by a variable-size data portion |
| 60 |
(which may be empty) specific to the requested operation |
| 61 |
(the requested operation is indicated by |
| 62 |
.IR opcode ). |
| 63 |
.P |
| 64 |
The daemon should then process the request |
| 65 |
and |
| 66 |
\[em]if applicable\[em] |
| 67 |
send a reply |
| 68 |
(almost all operations require a reply; |
| 69 |
if they do not, |
| 70 |
this is documented below), |
| 71 |
by performing a |
| 72 |
.BR write (2) |
| 73 |
to the file descriptor. |
| 74 |
All replies must start with the following header: |
| 75 |
.P |
| 76 |
.in +4n |
| 77 |
.EX |
| 78 |
struct fuse_out_header { |
| 79 |
uint32_t len; /* Total size of data written to |
| 80 |
the file descriptor */ |
| 81 |
int32_t error; /* Any error that occurred (0 if none) */ |
| 82 |
uint64_t unique; /* The value from the |
| 83 |
corresponding request */ |
| 84 |
}; |
| 85 |
.EE |
| 86 |
.in |
| 87 |
.P |
| 88 |
This header is also followed by (potentially empty) variable-sized |
| 89 |
data depending on the executed request. |
| 90 |
However, if the reply is an error reply (i.e., |
| 91 |
.I error |
| 92 |
is set), |
| 93 |
then no further payload data should be sent, independent of the request. |
| 94 |
.\" |
| 95 |
.SS Exchanged messages |
| 96 |
This section should contain documentation for each of the messages |
| 97 |
in the protocol. |
| 98 |
This manual page is currently incomplete, |
| 99 |
so not all messages are documented. |
| 100 |
For each message, first the struct sent by the kernel is given, |
| 101 |
followed by a description of the semantics of the message. |
| 102 |
.TP |
| 103 |
.B FUSE_INIT |
| 104 |
.IP |
| 105 |
.in +4n |
| 106 |
.EX |
| 107 |
struct fuse_init_in { |
| 108 |
uint32_t major; |
| 109 |
uint32_t minor; |
| 110 |
uint32_t max_readahead; /* Since protocol v7.6 */ |
| 111 |
uint32_t flags; /* Since protocol v7.6 */ |
| 112 |
}; |
| 113 |
.EE |
| 114 |
.in |
| 115 |
.IP |
| 116 |
This is the first request sent by the kernel to the daemon. |
| 117 |
It is used to negotiate the protocol version and other filesystem parameters. |
| 118 |
Note that the protocol version may affect the layout of any structure |
| 119 |
in the protocol (including this structure). |
| 120 |
The daemon must thus remember the negotiated version |
| 121 |
and flags for each session. |
| 122 |
As of the writing of this man page, |
| 123 |
the highest supported kernel protocol version is |
| 124 |
.IR 7.26 . |
| 125 |
.IP |
| 126 |
Users should be aware that the descriptions in this manual page |
| 127 |
may be incomplete or incorrect for older or more recent protocol versions. |
| 128 |
.IP |
| 129 |
The reply for this request has the following format: |
| 130 |
.IP |
| 131 |
.in +4n |
| 132 |
.EX |
| 133 |
struct fuse_init_out { |
| 134 |
uint32_t major; |
| 135 |
uint32_t minor; |
| 136 |
uint32_t max_readahead; /* Since v7.6 */ |
| 137 |
uint32_t flags; /* Since v7.6; some flags bits |
| 138 |
were introduced later */ |
| 139 |
uint16_t max_background; /* Since v7.13 */ |
| 140 |
uint16_t congestion_threshold; /* Since v7.13 */ |
| 141 |
uint32_t max_write; /* Since v7.5 */ |
| 142 |
uint32_t time_gran; /* Since v7.6 */ |
| 143 |
uint32_t unused[9]; |
| 144 |
}; |
| 145 |
.EE |
| 146 |
.in |
| 147 |
.IP |
| 148 |
If the major version supported by the kernel is larger than that supported |
| 149 |
by the daemon, the reply shall consist of only |
| 150 |
.I uint32_t major |
| 151 |
(following the usual header), |
| 152 |
indicating the largest major version supported by the daemon. |
| 153 |
The kernel will then issue a new |
| 154 |
.B FUSE_INIT |
| 155 |
request conforming to the older version. |
| 156 |
In the reverse case, the daemon should |
| 157 |
quietly fall back to the kernel's major version. |
| 158 |
.IP |
| 159 |
The negotiated minor version is considered to be the minimum |
| 160 |
of the minor versions provided by the daemon and the kernel and |
| 161 |
both parties should use the protocol corresponding to said minor version. |
| 162 |
.TP |
| 163 |
.B FUSE_GETATTR |
| 164 |
.IP |
| 165 |
.in +4n |
| 166 |
.EX |
| 167 |
struct fuse_getattr_in { |
| 168 |
uint32_t getattr_flags; |
| 169 |
uint32_t dummy; |
| 170 |
uint64_t fh; /* Set only if |
| 171 |
(getattr_flags & FUSE_GETATTR_FH) |
| 172 |
}; |
| 173 |
.EE |
| 174 |
.in |
| 175 |
.IP |
| 176 |
The requested operation is to compute the attributes to be returned |
| 177 |
by |
| 178 |
.BR stat (2) |
| 179 |
and similar operations for the given filesystem object. |
| 180 |
The object for which the attributes should be computed is indicated |
| 181 |
either by |
| 182 |
.I header\->nodeid |
| 183 |
or, if the |
| 184 |
.B FUSE_GETATTR_FH |
| 185 |
flag is set, by the file handle |
| 186 |
.IR fh . |
| 187 |
The latter case of operation is analogous to |
| 188 |
.BR fstat (2). |
| 189 |
.IP |
| 190 |
For performance reasons, these attributes may be cached in the kernel for |
| 191 |
a specified duration of time. |
| 192 |
While the cache timeout has not been exceeded, |
| 193 |
the attributes will be served from the cache and will not cause additional |
| 194 |
.B FUSE_GETATTR |
| 195 |
requests. |
| 196 |
.IP |
| 197 |
The computed attributes and the requested |
| 198 |
cache timeout should then be returned in the following structure: |
| 199 |
.IP |
| 200 |
.in +4n |
| 201 |
.EX |
| 202 |
struct fuse_attr_out { |
| 203 |
/* Attribute cache duration (seconds + nanoseconds) */ |
| 204 |
uint64_t attr_valid; |
| 205 |
uint32_t attr_valid_nsec; |
| 206 |
uint32_t dummy; |
| 207 |
struct fuse_attr { |
| 208 |
uint64_t ino; |
| 209 |
uint64_t size; |
| 210 |
uint64_t blocks; |
| 211 |
uint64_t atime; |
| 212 |
uint64_t mtime; |
| 213 |
uint64_t ctime; |
| 214 |
uint32_t atimensec; |
| 215 |
uint32_t mtimensec; |
| 216 |
uint32_t ctimensec; |
| 217 |
uint32_t mode; |
| 218 |
uint32_t nlink; |
| 219 |
uint32_t uid; |
| 220 |
uint32_t gid; |
| 221 |
uint32_t rdev; |
| 222 |
uint32_t blksize; |
| 223 |
uint32_t padding; |
| 224 |
} attr; |
| 225 |
}; |
| 226 |
.EE |
| 227 |
.in |
| 228 |
.TP |
| 229 |
.B FUSE_ACCESS |
| 230 |
.IP |
| 231 |
.in +4n |
| 232 |
.EX |
| 233 |
struct fuse_access_in { |
| 234 |
uint32_t mask; |
| 235 |
uint32_t padding; |
| 236 |
}; |
| 237 |
.EE |
| 238 |
.in |
| 239 |
.IP |
| 240 |
If the |
| 241 |
.I default_permissions |
| 242 |
mount options is not used, this request may be used for permissions checking. |
| 243 |
No reply data is expected, but errors may be indicated |
| 244 |
as usual by setting the |
| 245 |
.I error |
| 246 |
field in the reply header (in particular, access denied errors |
| 247 |
may be indicated by returning |
| 248 |
.BR \-EACCES ). |
| 249 |
.TP |
| 250 |
.B FUSE_OPEN |
| 251 |
.TQ |
| 252 |
.B FUSE_OPENDIR |
| 253 |
.in +4n |
| 254 |
.EX |
| 255 |
struct fuse_open_in { |
| 256 |
uint32_t flags; /* The flags that were passed |
| 257 |
to the open(2) */ |
| 258 |
uint32_t unused; |
| 259 |
}; |
| 260 |
.EE |
| 261 |
.in |
| 262 |
.IP |
| 263 |
The requested operation is to open the node indicated by |
| 264 |
.IR header\->nodeid . |
| 265 |
The exact semantics of what this means will depend on the |
| 266 |
filesystem being implemented. |
| 267 |
However, at the very least the |
| 268 |
filesystem should validate that the requested |
| 269 |
.I flags |
| 270 |
are valid for the indicated resource and then send a reply with the |
| 271 |
following format: |
| 272 |
.IP |
| 273 |
.in +4n |
| 274 |
.EX |
| 275 |
struct fuse_open_out { |
| 276 |
uint64_t fh; |
| 277 |
uint32_t open_flags; |
| 278 |
uint32_t padding; |
| 279 |
}; |
| 280 |
.EE |
| 281 |
.in |
| 282 |
.IP |
| 283 |
The |
| 284 |
.I fh |
| 285 |
field is an opaque identifier that the kernel will use to refer |
| 286 |
to this resource |
| 287 |
The |
| 288 |
.I open_flags |
| 289 |
field is a bit mask of any number of the flags |
| 290 |
that indicate properties of this file handle to the kernel: |
| 291 |
.RS 7 |
| 292 |
.TP 18 |
| 293 |
.B FOPEN_DIRECT_IO |
| 294 |
Bypass page cache for this open file. |
| 295 |
.TP |
| 296 |
.B FOPEN_KEEP_CACHE |
| 297 |
Don't invalidate the data cache on open. |
| 298 |
.TP |
| 299 |
.B FOPEN_NONSEEKABLE |
| 300 |
The file is not seekable. |
| 301 |
.RE |
| 302 |
.TP |
| 303 |
.B FUSE_READ |
| 304 |
.TQ |
| 305 |
.B FUSE_READDIR |
| 306 |
.IP |
| 307 |
.in +4n |
| 308 |
.EX |
| 309 |
struct fuse_read_in { |
| 310 |
uint64_t fh; |
| 311 |
uint64_t offset; |
| 312 |
uint32_t size; |
| 313 |
uint32_t read_flags; |
| 314 |
uint64_t lock_owner; |
| 315 |
uint32_t flags; |
| 316 |
uint32_t padding; |
| 317 |
}; |
| 318 |
.EE |
| 319 |
.in |
| 320 |
.IP |
| 321 |
The requested action is to read up to |
| 322 |
.I size |
| 323 |
bytes of the file or directory, starting at |
| 324 |
.IR offset . |
| 325 |
The bytes should be returned directly following the usual reply header. |
| 326 |
.TP |
| 327 |
.B FUSE_INTERRUPT |
| 328 |
.in +4n |
| 329 |
.EX |
| 330 |
struct fuse_interrupt_in { |
| 331 |
uint64_t unique; |
| 332 |
}; |
| 333 |
.EE |
| 334 |
.in |
| 335 |
.IP |
| 336 |
The requested action is to cancel the pending operation indicated by |
| 337 |
.IR unique . |
| 338 |
This request requires no response. |
| 339 |
However, receipt of this message does |
| 340 |
not by itself cancel the indicated operation. |
| 341 |
The kernel will still expect a reply to said operation (e.g., an |
| 342 |
.I EINTR |
| 343 |
error or a short read). |
| 344 |
At most one |
| 345 |
.B FUSE_INTERRUPT |
| 346 |
request will be issued for a given operation. |
| 347 |
After issuing said operation, |
| 348 |
the kernel will wait uninterruptibly for completion of the indicated request. |
| 349 |
.TP |
| 350 |
.B FUSE_LOOKUP |
| 351 |
Directly following the header is a filename to be looked up in the directory |
| 352 |
indicated by |
| 353 |
.IR header\->nodeid . |
| 354 |
The expected reply is of the form: |
| 355 |
.IP |
| 356 |
.in +4n |
| 357 |
.EX |
| 358 |
struct fuse_entry_out { |
| 359 |
uint64_t nodeid; /* Inode ID */ |
| 360 |
uint64_t generation; /* Inode generation */ |
| 361 |
uint64_t entry_valid; |
| 362 |
uint64_t attr_valid; |
| 363 |
uint32_t entry_valid_nsec; |
| 364 |
uint32_t attr_valid_nsec; |
| 365 |
struct fuse_attr attr; |
| 366 |
}; |
| 367 |
.EE |
| 368 |
.in |
| 369 |
.IP |
| 370 |
The combination of |
| 371 |
.I nodeid |
| 372 |
and |
| 373 |
.I generation |
| 374 |
must be unique for the filesystem's lifetime. |
| 375 |
.IP |
| 376 |
The interpretation of timeouts and |
| 377 |
.I attr |
| 378 |
is as for |
| 379 |
.BR FUSE_GETATTR . |
| 380 |
.TP |
| 381 |
.B FUSE_FLUSH |
| 382 |
.in +4n |
| 383 |
.EX |
| 384 |
struct fuse_flush_in { |
| 385 |
uint64_t fh; |
| 386 |
uint32_t unused; |
| 387 |
uint32_t padding; |
| 388 |
uint64_t lock_owner; |
| 389 |
}; |
| 390 |
.EE |
| 391 |
.in |
| 392 |
.IP |
| 393 |
The requested action is to flush any pending changes to the indicated |
| 394 |
file handle. |
| 395 |
No reply data is expected. |
| 396 |
However, an empty reply message |
| 397 |
still needs to be issued once the flush operation is complete. |
| 398 |
.TP |
| 399 |
.B FUSE_RELEASE |
| 400 |
.TQ |
| 401 |
.B FUSE_RELEASEDIR |
| 402 |
.in +4n |
| 403 |
.EX |
| 404 |
struct fuse_release_in { |
| 405 |
uint64_t fh; |
| 406 |
uint32_t flags; |
| 407 |
uint32_t release_flags; |
| 408 |
uint64_t lock_owner; |
| 409 |
}; |
| 410 |
.EE |
| 411 |
.in |
| 412 |
.IP |
| 413 |
These are the converse of |
| 414 |
.B FUSE_OPEN |
| 415 |
and |
| 416 |
.B FUSE_OPENDIR |
| 417 |
respectively. |
| 418 |
The daemon may now free any resources associated with the |
| 419 |
file handle |
| 420 |
.I fh |
| 421 |
as the kernel will no longer refer to it. |
| 422 |
There is no reply data associated with this request, |
| 423 |
but a reply still needs to be issued once the request has |
| 424 |
been completely processed. |
| 425 |
.TP |
| 426 |
.B FUSE_STATFS |
| 427 |
This operation implements |
| 428 |
.BR statfs (2) |
| 429 |
for this filesystem. |
| 430 |
There is no input data associated with this request. |
| 431 |
The expected reply data has the following structure: |
| 432 |
.IP |
| 433 |
.in +4n |
| 434 |
.EX |
| 435 |
struct fuse_kstatfs { |
| 436 |
uint64_t blocks; |
| 437 |
uint64_t bfree; |
| 438 |
uint64_t bavail; |
| 439 |
uint64_t files; |
| 440 |
uint64_t ffree; |
| 441 |
uint32_t bsize; |
| 442 |
uint32_t namelen; |
| 443 |
uint32_t frsize; |
| 444 |
uint32_t padding; |
| 445 |
uint32_t spare[6]; |
| 446 |
}; |
| 447 |
\& |
| 448 |
struct fuse_statfs_out { |
| 449 |
struct fuse_kstatfs st; |
| 450 |
}; |
| 451 |
.EE |
| 452 |
.in |
| 453 |
.IP |
| 454 |
For the interpretation of these fields, see |
| 455 |
.BR statfs (2). |
| 456 |
.SH ERRORS |
| 457 |
.TP |
| 458 |
.B E2BIG |
| 459 |
Returned from |
| 460 |
.BR read (2) |
| 461 |
operations when the kernel's request is too large for the provided buffer |
| 462 |
and the request was |
| 463 |
.BR FUSE_SETXATTR . |
| 464 |
.TP |
| 465 |
.B EINVAL |
| 466 |
Returned from |
| 467 |
.BR write (2) |
| 468 |
if validation of the reply failed. |
| 469 |
Not all mistakes in replies will be caught by this validation. |
| 470 |
However, basic mistakes, such as short replies or an incorrect |
| 471 |
.I unique |
| 472 |
value, are detected. |
| 473 |
.TP |
| 474 |
.B EIO |
| 475 |
Returned from |
| 476 |
.BR read (2) |
| 477 |
operations when the kernel's request is too large for the provided buffer. |
| 478 |
.IP |
| 479 |
.IR Note : |
| 480 |
There are various ways in which incorrect use of these interfaces can cause |
| 481 |
operations on the provided filesystem's files and directories to fail with |
| 482 |
.BR EIO . |
| 483 |
Among the possible incorrect uses are: |
| 484 |
.RS |
| 485 |
.IP \[bu] 3 |
| 486 |
changing |
| 487 |
.I mode & S_IFMT |
| 488 |
for an inode that has previously been reported to the kernel; |
| 489 |
or |
| 490 |
.IP \[bu] |
| 491 |
giving replies to the kernel that are shorter than what the kernel expected. |
| 492 |
.RE |
| 493 |
.TP |
| 494 |
.B ENODEV |
| 495 |
Returned from |
| 496 |
.BR read (2) |
| 497 |
and |
| 498 |
.BR write (2) |
| 499 |
if the FUSE filesystem was unmounted. |
| 500 |
.TP |
| 501 |
.B EPERM |
| 502 |
Returned from operations on a |
| 503 |
.I /dev/fuse |
| 504 |
file descriptor that has not been mounted. |
| 505 |
.SH STANDARDS |
| 506 |
Linux. |
| 507 |
.SH NOTES |
| 508 |
The following messages are not yet documented in this manual page: |
| 509 |
.P |
| 510 |
.\" FIXME: Document the following. |
| 511 |
.in +4n |
| 512 |
.EX |
| 513 |
.B FUSE_BATCH_FORGET |
| 514 |
.B FUSE_BMAP |
| 515 |
.B FUSE_CREATE |
| 516 |
.B FUSE_DESTROY |
| 517 |
.B FUSE_FALLOCATE |
| 518 |
.B FUSE_FORGET |
| 519 |
.B FUSE_FSYNC |
| 520 |
.B FUSE_FSYNCDIR |
| 521 |
.B FUSE_GETLK |
| 522 |
.B FUSE_GETXATTR |
| 523 |
.B FUSE_IOCTL |
| 524 |
.B FUSE_LINK |
| 525 |
.B FUSE_LISTXATTR |
| 526 |
.B FUSE_LSEEK |
| 527 |
.B FUSE_MKDIR |
| 528 |
.B FUSE_MKNOD |
| 529 |
.B FUSE_NOTIFY_REPLY |
| 530 |
.B FUSE_POLL |
| 531 |
.B FUSE_READDIRPLUS |
| 532 |
.B FUSE_READLINK |
| 533 |
.B FUSE_REMOVEXATTR |
| 534 |
.B FUSE_RENAME |
| 535 |
.B FUSE_RENAME2 |
| 536 |
.B FUSE_RMDIR |
| 537 |
.B FUSE_SETATTR |
| 538 |
.B FUSE_SETLK |
| 539 |
.B FUSE_SETLKW |
| 540 |
.B FUSE_SYMLINK |
| 541 |
.B FUSE_UNLINK |
| 542 |
.B FUSE_WRITE |
| 543 |
.EE |
| 544 |
.in |
| 545 |
.SH SEE ALSO |
| 546 |
.BR fusermount (1), |
| 547 |
.BR mount.fuse (8) |