Writing a FUSE Filesystem: a Tutorial

One of the real contributions of Unix has been the view that "everything is a file". A tremendous number of radically different sorts of objects, from data storage to file format conversions to internal operating system data structures, have been mapped to th file abstraction.

One of the more recent directions this view has taken has been Filesystems in User Space, or FUSE (no, the acronym really doesn't work. Oh well). The idea here is that if you can envision your interaction with an object in terms of a directory structure and filesystem operations, you can write a FUSE file system to provide that interaction. You just write code that implements file operations like open(), read(), and write(); when your filesystem is mounted, programs are able to access the data using the standard file operation system calls, which call your code.

There are many documents on the web describing how FUSE works and how to install and use a FUSE filesystem, but I haven't come across any that try to describe how to go about actually writing one. The goal of this tutorial is to meet what I see as a need for such a document.

This tutorial introduces FUSE using a filesystem I call the "Big Brother File System" — the reason for the name is that bb is watching. the filesystem simply passes every operation down to an underlying directory, but logs the operation.

This tutorial, together with its associated example filesystem, is available as a tarball at http://www.cs.nmsu.edu/~pfeiffer/fuse-tutorial.tgz.

I am not affiliated with the FUSE project in any way, except as a user. my descriptions of the interface to fuse, and of techniques to work with it, are a distillation of my reading of the existing documentation, and my experience working with it. consequently, any errors are mine.

Organization

The tutorial is divided into the following sections:

Files and Naming Conventions in This Tutorial
This section describes the files distributed as a part of this tutorial, and the naming conventions for the functions in the bbfs filesystem. It's really there to provide an overview of the whole tutorial and filesystem, not to directly provide information on FUSE.

Callbacks and struct fuse_operations
This is the heart of a FUSE filesystem, and of this tutorial. The central concepts are discussed here.

Extra Information on Unclear FUSE Functions
The intent of this section is to give some extra information on FUSE functions that seem a little unclear. So far, the only thing in here is readdir(). I may combine this section with the next one...

Parsing the Command Line and Initializing FUSE
Getting your program started.

Private Data and Related Topics
A filesystem may need to maintain some private state. This section discusses this.

Running BBFS
Finally, a little bit of information on mounting a filesystem with bbfs, watching the log, and unmounting it.

Next: Files and Naming Conventions in This Tutorial


Last modified: Thu Oct 8 09:58:49 MDT 2009