FB_SETUP(9)

✨ FB_SETUP(9) ✨

okay bestie, this one is straight out of the Kernel Developer's Manual, and it's giving kernel-messaging-for-FUSE realness 🫶 no cap.

💖 NAME 💖

fb_setup, fb_queue, fb_delete — kernel messaging mechanism for file system in userland (FUSE)

🌸 SYNOPSIS 🌸

#include <sys/fusebuf.h>

struct fusebuf *
fb_setup(size_t size, ino_t inode, int type, struct proc *p);

int
fb_queue(dev_t dev, struct fusebuf *fbuf);

void
fb_delete(struct fusebuf *fbuf);

#define FUSEBUFMAXSIZE  (4096*1024)
#define FUSEBUFSIZE     (sizeof(struct fusebuf))

struct fb_hdr {
        SIMPLEQ_ENTRY(fusebuf)  fh_next;
        size_t                  fh_len;
        int                     fh_err;
        int                     fh_type;
        ino_t                   fh_ino;
        uint64_t                fh_uuid;
};

struct fb_io {
        uint64_t        fi_fd;
        ino_t           fi_ino;
        off_t           fi_off;
        size_t          fi_len;
        mode_t          fi_mode;
        uint32_t        fi_flags;
};

struct fusebuf {
        struct fb_hdr   fb_hdr;
        union {
                struct statvfs  FD_stat;
                struct stat     FD_attr;
                struct fb_io    FD_io;

        } FD;
        uint8_t *fb_dat;
};

#define fb_next         fb_hdr.fh_next
#define fb_len          fb_hdr.fh_len
#define fb_err          fb_hdr.fh_err
#define fb_type         fb_hdr.fh_type
#define fb_ino          fb_hdr.fh_ino
#define fb_uuid         fb_hdr.fh_uuid

#define fb_stat         FD.FD_stat
#define fb_attr         FD.FD_attr
#define fb_io_fd        FD.FD_io.fi_fd
#define fb_io_ino       FD.FD_io.fi_ino
#define fb_io_off       FD.FD_io.fi_off
#define fb_io_len       FD.FD_io.fi_len
#define fb_io_mode      FD.FD_io.fi_mode
#define fb_io_flags     FD.FD_io.fi_flags

💅 DESCRIPTION 💅

These functions are the whole vibe for managing the kernel messaging mechanism for fuse(4) file systems. It is based on mbuf(9) — yes ma'am, classic behavior 💖

Every single FUSE operation fits inside one fusebuf, except for read, write, and readdirs — those get split into several fusebufs, with a changing value in fb_io_off for each one. The size of a fusebuf is FUSEBUFSIZE. Periodt ✨

A fusebuf structure is defined as an fb_hdr followed by a structure containing a union and a buffer F_Dat. The header contains the following elements:

• fh_next — a SIMPLEQ_ENTRY(3) needed to store the different fusebufs stored with fb_queue().
• fh_len — indicates the amount of data in F_dat.
• fh_resid — used for partial fuse(4) reads. If the read does not fill the fusebuf, the number of bytes of F_dat written are stored in this field.
• fh_err — indicates the errno(2) failure of a fusebuf.
• fh_type — indicates the type of fusebuf transaction (see below).
• fh_ino — indicates the inode on which the fuse(4) operation is done.
• fh_uuid — UUID to track the answer. This number is generated with arc4random(9).

The fh_type variable can take the following values:

• FBT_LOOKUP — the fusebuf is a lookup operation.
• FBT_GETATTR — the fusebuf is a gettattr operation.
• FBT_SETATTR — the fusebuf is a setattr operation.
• FBT_READLINK — the fusebuf is a readlink operation.
• FBT_SYMLINK — the fusebuf is a symlink operation.
• FBT_MKNOD — the fusebuf is a mknod operation.
• FBT_MKDIR — the fusebuf is a mkdir operation.
• FBT_UNLINK — the fusebuf is an unlink operation.
• FBT_RMDIR — the fusebuf is an rmdir operation.
• FBT_RENAME — the fusebuf is a rename operation.
• FBT_LINK — the fusebuf is a link operation.
• FBT_OPEN — the fusebuf is an open operation.
• FBT_READ — the fusebuf is a read operation.
• FBT_WRITE — the fusebuf is a write operation.
• FBT_STATFS — the fusebuf is a statfs operation.
• FBT_RELEASE — the fusebuf is a file close operation.
• FBT_FSYNC — the fusebuf is a file sync operation.
• FBT_FLUSH — the fusebuf is a flush operation.
• FBT_INIT — the fusebuf initializes the FUSE connection.
• FBT_OPENDIR — the fusebuf is an opendir operation.
• FBT_READDIR — the fusebuf is a readdir operation.
• FBT_RELEASEDIR — the fusebuf is a close dir operation.
• FBT_FSYNCDIR — the fusebuf is a dir sync operation.
• FBT_ACCESS — the fusebuf is an access operation.
• FBT_DESTROY — the fusebuf closes the FUSE connection.

All the data needed by the FUSE clients is contained in the F_dat structure. This structure contains a union FD of frequently used type and a buffer F_databuf to send data to libfuse. The union contains the following elements:

• FD_stat — a struct statvfs(3) filled in by the FUSE client statfs for the FUSE VFS statfs code.
• FD_attr — used by the getattr and setattr calls.
• FD_io — contains all fields commonly used by FUSE client callbacks to provide information to FUSE vnops. It is used by access, readdir, release, releasedir, read, write, mkdir, and setattr.

Setattr uses a struct fb_io and a struct stat. Settattr uses FD_stat and encapsulates a struct fb_io in F_databuf with fbtod.

Fusebufs can be deleted with the fb_delete() helper. slay 🫶

---

👀 SEE ALSO 👀

errno(2), fuse_main(3), queue(3), statvfs(3), fuse(4), arc4random(9), mbuf(9)

🦋 HISTORY 🦋

The fb_setup API first appeared in OpenBSD 5.4. iconic behavior honestly 🔥

mwah 💋 this page's footer energy is Debian, dated November 30, 2017 — FB_SETUP(9) out 💅