dfuse 0.5.0

dfuse

dfuse is a D language binding for the high level fuse library. It allows to write a fuse filesystem for Linux or Mac OS (using osxfuse) in D.

Fuse is a library and kernel extension to write filesystems in userspace. These filesystems are easy to implement and have access to userland components like HTTP libraries, etc. For more information about fuse see: http://fuse.sourceforge.net.

Examples

A simple filesystems implementing a directory listing can be found in the example/ directory. You can build the examples using:

$ cd example
$ dub build  # or: $ dmd -i -I../source -L-lfuse simplefs.d
$ mkdir /mnt/simplefs
$ ./simplefs /mnt/simplefs

Implementing a filesystem

dfuse provides a high level interface for libfuse. To implement a filesystem, extend the Operations class in the dfuse.fuse module:

import dfuse.fuse;

class MyFS : Operations
{
    override void getattr(const(char)[] path, ref stat_t s)
    {
        /* implementation */
        throw new FuseException(EOPNOTSUPP);
    }
    
    override string[] readdir(const(char)[] path)
    {
       return [/*...list of files...*/];
    }
    
    override ulong read(const(char)[] path, ubyte[] buf, ulong offset)
    {
       /* implementation */
       throw new FuseException(EOPNOTSUPP);
    }
}

A minimal filesystem implements Operations.getattr(), Operations.access(), Operations.readdir(), Operations.read(). See dfuse/fuse.d for implementation specific details.

To mount a filesystem use a Fuse object and call mount:

import dfuse.fuse;

int main(string[] args)
{
    /* foreground=true, threading=false */
    auto fs = new Fuse("MyFS", true, false);
    fs.mount(new MyFS(), "/mnt", ["allow_other"]);
}

Error conditions are handled by throwin a FuseException with the appropriate error number. See man 3 errno for more information about errno.

Requirements

dfuse requires:

• Mac OS X or Linux
• fuse >= 2.8.0 or osxfuse >= 2.6.0
• DMD/Druntime/Phobos >= 2.065

Building dfuse

dfuse comes with a Dub configuration file, making it usable as a Dub package.

Alternatively, it is usable with common D recursive compilation tools (dmd -i / rdmd / rund).

Dub

In order to compile dfuse on Linux:

$ dub build -b release
or
$ dub build -b debug
to build a debug version

Recursive compilation

• Make sure the dfuse source directory is in your compiler search path.
• import dfuse.fuse; in your program.
• Link against the fuse library, e.g. by adding -L-lfuse to the compiler's command line, or by adding pragma(lib, "fuse"); in your program.

How dfuse works

dfuse is a simple D wrapper. It exposes a lowelevel interface to the libfuse C functions in c/fuse/fuse.d. The lowlevel interface preserves C types.

A highlevel interface is provided by fs/fuse.d. The D interface initializes fuse filsystems operations structure and installs it's own handlers. Every dfuse handler converts C types to D types and is trapping FuseExceptions used for error handling. The handlers keep track of the initialized Operations object and call the appropriate method once types are converted and pass the result into the D layer.

The user facing interface is the Operations class in fs/fuse.d. It provides default implementations for all handlers and every method can be invidually overwritten to provide an interface.

Issues and Bugs

If you encounter issues or bugs with dfuse, please file an issue on github. Please ensure that you maintain a constructive feedback atmosphere and if possible attach a reproduction step. If you have any questions, feel free to write to the D mailinglist or ask in IRC.

Pull requests are highly appreciated!

Join the dfuse community

• Website: https://github.com/dlang-community/dfuse/wiki
• Mailing list: The D Mailinglist
• irc: irc.freenode.net #d

License

dfuse is Boost-licensed. We also provide an additional patent grant.