fuse(4)

📦

version 6.20 · 14 versions

6.20 · arch rolling, nixpkgs unstable (latest)
6.13 · opensuse-leap 16.0
6.04 · centos-stream 9
6.06 · centos-stream 10
nixpkgs unstable
6.16 · alpine 3.23
6.18 · alpine 3.24, nixos 26.05
6.19 · arch rolling, ubuntu stonking
5.10 · ubuntu jammy
6.7 · ubuntu noble
6.13 · alpine 3.22, fedora 43, fedora 44
6.03 · debian bookworm
6.17 · ubuntu resolute
6.9.1 · debian trixie, fedora 43, ubuntu questing

🌸 NAME 🌸

fuse — Filesystem in Userspace (FUSE) device 💖

okay so bestie, this is the manual page for the super iconic FUSE device. no cap.

✨ SYNOPSIS ✨

#include <linux/fuse.h>

🦋 DESCRIPTION 🦋

okay so picture this: this device? it's literally THE main interface between the FUSE filesystem driver and a user-space process that wants to provide the filesystem. (we're gonna call that whole process the filesystem daemon for the rest of this page, k? 💅) This manual page is for anyone who wants to understand the kernel interface itself. If you're actually implementing a FUSE filesystem, you might wanna use a user-space library like libfuse that abstracts away the low-level interface. it's giving convenience, honestly.

At its core, FUSE is a simple client-server protocol, where the Linux kernel is the client and the daemon is the server. After getting a file descriptor for this device, the daemon may read(2) requests from that file descriptor and is expected to write(2) back its replies. and this part is important: a file descriptor is associated with a unique FUSE filesystem. so like, opening a second copy of this device will NOT allow access to resources created through the first file descriptor (and vice versa). they're separate. periodt.

🧚 The basic protocol 🧚

Every message that the daemon reads starts with a header described by this struct:

struct fuse_in_header {
    uint32_t len;       /* Total size of the data,
                           including this header */
    uint32_t opcode;    /* The kind of operation (see below) */
    uint64_t unique;    /* A unique identifier for this request */
    uint64_t nodeid;    /* ID of the filesystem object
                           being operated on */
    uint32_t uid;       /* UID of the requesting process */
    uint32_t gid;       /* GID of the requesting process */
    uint32_t pid;       /* PID of the requesting process */
    uint32_t padding;
};

The header is followed by a variable-size data portion (which may be empty) specific to the requested operation (aka the opcode, bestie).

The daemon should then process the request and —if applicable— send a reply (almost all operations require a reply; if they don't, it's documented below), by doing a write(2) to the file descriptor. All replies must start with this header:

struct fuse_out_header {
    uint32_t len;       /* Total size of data written to
                           the file descriptor */
    int32_t  error;     /* Any error that occurred (0 if none) */
    uint64_t unique;    /* The value from the
                           corresponding request */
};

This header is also followed by (potentially empty) variable-sized data depending on the executed request. BUT if the reply is an error reply (i.e., error is set), then no further payload data should be sent, no matter what the request was. that's the rule.

🌈 Exchanged messages 🌈

This section should contain documentation for each of the messages in the protocol. This manual page is currently incomplete, so not all messages are documented. For each message, first the struct sent by the kernel is given, followed by a description of the semantics of the message.

💫 FUSE_INIT 💫

struct fuse_init_in {
    uint32_t major;
    uint32_t minor;
    uint32_t max_readahead; /* Since protocol v7.6 */
    uint32_t flags;         /* Since protocol v7.6 */
};

This is the first request sent by the kernel to the daemon. It's used to negotiate the protocol version and other filesystem parameters. Note that the protocol version may affect the layout of any structure in the protocol (including this structure). The daemon must thus remember the negotiated version and flags for each session. As of the writing of this man page, the highest supported kernel protocol version is 7.26.

Users should be aware that the descriptions in this manual page may be incomplete or incorrect for older or more recent protocol versions. 😬

The reply for this request has this format:

struct fuse_init_out {
    uint32_t major;
    uint32_t minor;
    uint32_t max_readahead;   /* Since v7.6 */
    uint32_t flags;           /* Since v7.6; some flags bits
                                 were introduced later */
    uint16_t max_background;  /* Since v7.13 */
    uint16_t congestion_threshold;  /* Since v7.13 */
    uint32_t max_write;       /* Since v7.5 */
    uint32_t time_gran;       /* Since v7.6 */
    uint32_t unused[9];
};

If the major version supported by the kernel is larger than that supported by the daemon, the reply shall consist of only uint32_t major (following the usual header), indicating the largest major version supported by the daemon. The kernel will then issue a new FUSE_INIT request conforming to the older version. In the reverse case, the daemon should quietly fall back to the kernel's major version. no drama.

The negotiated minor version is considered to be the minimum of the minor versions provided by the daemon and the kernel, and both parties should use the protocol corresponding to said minor version. it's a whole collaboration vibe.

💅 FUSE_GETATTR 💅

struct fuse_getattr_in {
    uint32_t getattr_flags;
    uint32_t dummy;
    uint64_t fh;      /* Set only if
                         (getattr_flags & FUSE_GETATTR_FH)
};

The requested operation is to compute the attributes to be returned by stat(2) and similar operations for the given filesystem object. The object for which the attributes should be computed is indicated either by header->nodeid or, if the FUSE_GETATTR_FH flag is set, by the file handle fh. The latter case of operation is analogous to fstat(2).

For performance reasons, these attributes may be cached in the kernel for a specified duration of time. While the cache timeout has not been exceeded, the attributes will be served from the cache and will not cause additional FUSE_GETATTR requests. slay for efficiency.

The computed attributes and the requested cache timeout should then be returned in this structure:

struct fuse_attr_out {
    /* Attribute cache duration (seconds + nanoseconds) */
    uint64_t attr_valid;
    uint32_t attr_valid_nsec;
    uint32_t dummy;
    struct fuse_attr {
        uint64_t ino;
        uint64_t size;
        uint64_t blocks;
        uint64_t atime;
        uint64_t mtime;
        uint64_t ctime;
        uint32_t atimensec;
        uint32_t mtimensec;
        uint32_t ctimensec;
        uint32_t mode;
        uint32_t nlink;
        uint32_t uid;
        uint32_t gid;
        uint32_t rdev;
        uint32_t blksize;
        uint32_t padding;
    } attr;
};

🎀 FUSE_ACCESS 🎀

struct fuse_access_in {
    uint32_t mask;
    uint32_t padding;
};

If the default_permissions mount option is not used, this request may be used for permissions checking. No reply data is expected, but errors may be indicated as usual by setting the error field in the reply header (in particular, access denied errors may be indicated by returning -EACCES). so like, if someone's not allowed? you can just say no with that error code.

🌸 FUSE_OPEN / FUSE_OPENDIR 🌸

struct fuse_open_in {
    uint32_t flags;     /* The flags that were passed
                           to the open(2) */
    uint32_t unused;
};

The requested operation is to open the node indicated by header->nodeid. The exact semantics of what this means will depend on the filesystem being implemented. However, at the very least the filesystem should validate that the requested flags are valid for the indicated resource and then send a reply with this format:

struct fuse_open_out {
    uint64_t fh;
    uint32_t open_flags;
    uint32_t padding;
};

The fh field is an opaque identifier that the kernel will use to refer to this resource. The open_flags field is a bit mask of any number of the flags that indicate properties of this file handle to the kernel:

FOPEN_DIRECT_IO — Bypass page cache for this open file.
FOPEN_KEEP_CACHE — Don't invalidate the data cache on open.
FOPEN_NONSEEKABLE — The file is not seekable.

🦋 FUSE_READ / FUSE_READDIR 🦋

struct fuse_read_in {
    uint64_t fh;
    uint64_t offset;
    uint32_t size;
    uint32_t read_flags;
    uint64_t lock_owner;
    uint32_t flags;
    uint32_t padding;
};

The requested action is to read up to size bytes of the file or directory, starting at offset. The bytes should be returned directly following the usual reply header. no extra fluff, just the goods.

⭐ FUSE_INTERRUPT ⭐

struct fuse_interrupt_in {
    uint64_t unique;
};

The requested action is to cancel the pending operation indicated by unique. This request requires no response. However, receipt of this message does not by itself cancel the indicated operation. The kernel will still expect a reply to said operation (e.g., an EINTR error or a short read). At most one FUSE_INTERRUPT request will be issued for a given operation. After issuing said operation, the kernel will wait uninterruptibly for completion of the indicated request. so like, you can't just ghost it, bestie.

👑 FUSE_LOOKUP 👑

Directly following the header is a filename to be looked up in the directory indicated by header->nodeid. The expected reply is of the form:

struct fuse_entry_out {
    uint64_t nodeid;            /* Inode ID */
    uint64_t generation;        /* Inode generation */
    uint64_t entry_valid;
    uint64_t attr_valid;
    uint32_t entry_valid_nsec;
    uint32_t attr_valid_nsec;
    struct fuse_attr attr;
};

Okay so the whole nodeid + generation combo? It has to be unique for the entire lifetime of the filesystem. Not "unique-ish", not "unique today", not "unique until I get bored". For the filesystem's whole entire life, bestie. 🫶

And the way the timeouts and attr work? Same deal as FUSE_GETATTR. Copy that energy. ✨

FUSE_FLUSH 🚿

struct fuse_flush_in {
    uint64_t fh;
    uint32_t unused;
    uint32_t padding;
    uint64_t lock_owner;
};

So the vibe here is: flush all the pending changes sitting on that file handle, kthanks. 💅

No reply data is expected — but bestie, listen, you still gotta send an empty reply message once the flush is done. Silence is not an answer here, the kernel is waiting. An empty reply is still a reply. 😌

FUSE_RELEASE & FUSE_RELEASEDIR 🎈

struct fuse_release_in {
    uint64_t fh;
    uint32_t flags;
    uint32_t release_flags;
    uint64_t lock_owner;
};

These two are the converse of FUSE_OPEN and FUSE_OPENDIR respectively — like, the mirror image, the closing bracket to their opening bracket. 🦋

From here the daemon may free any resources tied to the file handle fh, because the kernel is officially never gonna refer to it again. She's done. She's moved on. Let her go. 🕊️

Also: there's no reply data attached to this request… but (yes, you guessed it) a reply still needs to be issued once the request has been completely processed. Periodt. 💅

FUSE_STATFS 📊

This one implements statfs(2) for your filesystem. No input data, nothing going in — it's purely a "hey what's the status" situation.

The reply you're expected to send back looks like this:

struct fuse_kstatfs {
    uint64_t blocks;
    uint64_t bfree;
    uint64_t bavail;
    uint64_t files;
    uint64_t ffree;
    uint32_t bsize;
    uint32_t namelen;
    uint32_t frsize;
    uint32_t padding;
    uint32_t spare[6];
};

struct fuse_statfs_out {
    struct fuse_kstatfs st;
};

Wanna know what all those fields actually mean? Go look at statfs(2), babe, that's where the interpretation lives. 📖✨

ERRORS 😭💀

E2BIG — gets returned from read(2) operations when the kernel's request is too big for the buffer you provided and that request was FUSE_SETXATTR. Rude, but real.
EINVAL — gets returned from write(2) if validating your reply failed. And ngl, not every mistake in your replies will get caught by this validation. But the basic stuff — short replies, a wrong unique value, that kind of thing — yeah, that gets detected. 👀
EIO — gets returned from read(2) operations when the kernel's request is too big for the buffer you gave it.

Note, and this is important: there are multiple ways that using these interfaces wrong can make operations on your filesystem's files and directories fail with EIO. Among the possible incorrect uses: - changing mode & S_IFMT for an inode that has already been reported to the kernel; or - giving the kernel replies that are shorter than what the kernel expected.

ENODEV — gets returned from read(2) and write(2) if the FUSE filesystem was unmounted. She's gone, girl. Nothing to read from. 🪦
EPERM — gets returned from operations on a /dev/fuse file descriptor that hasn't been mounted. Like, you're knocking on a door that was never built. 🚪💀

STANDARDS ⭐

Linux. 🐧 That's it. That's the standard. Home turf.

NOTES 📝

Soooo, these messages are not yet documented in this manual page. Not me pointing at the gap in the docs — but yeah, they're listed here so you at least know their names exist. 🙈

FUSE_BATCH_FORGET
FUSE_BMAP
FUSE_CREATE
FUSE_DESTROY
FUSE_FALLOCATE
FUSE_FORGET
FUSE_FSYNC
FUSE_FSYNCDIR
FUSE_GETLK
FUSE_GETXATTR
FUSE_IOCTL
FUSE_LINK
FUSE_LISTXATTR
FUSE_LSEEK
FUSE_MKDIR
FUSE_MKNOD
FUSE_NOTIFY_REPLY
FUSE_POLL
FUSE_READDIRPLUS
FUSE_READLINK
FUSE_REMOVEXATTR
FUSE_RENAME
FUSE_RENAME2
FUSE_RMDIR
FUSE_SETATTR
FUSE_SETLK
FUSE_SETLKW
FUSE_SYMLINK
FUSE_UNLINK
FUSE_WRITE

iykyk 🌈