fuse

  1. fuse
    1. Description
      1. Warning
      2. Platform Notes
    2. API
    3. Author
    4. License

Description

A FUSE interface.

Installation requires the libfuse library and headers (API version 26) and CHICKEN 4.8.0 or newer.

The source for this extension is available at Bitbucket.

Warning

This extension is not yet stable. Its interface is subject to change, and I'd appreciate feedback and suggestions regarding the API.

Platform Notes

This extension is only officially supported on Linux. It has also been installed successfully on OpenBSD, FreeBSD and Mac OS X, but tested far less thoroughly on those platforms.

On Linux, each filesystem operation is executed in its own green (srfi-18) thread.

On other platforms, filesystem operations are synchronous (start-filesystem is single-threaded) and stop-filesystem is not supported.

API

[record] filesystem
[procedure] (filesystem? object) -> boolean

A filesystem is an opaque, defstruct-style record type representing a set of FUSE filesystem operations.

[procedure] (make-filesystem #!key <operation> ...) -> filesystem

Create a FUSE filesystem.

The keyword arguments to make-filesystem specify the resulting filesystem's callback procedures. Each <operation> should be one the following:

access:
(procedure path mode) -> value
chmod:
(procedure path mode) -> value
chown:
(procedure uid gid) -> value
create:
(procedure path mode) -> (or handle #f)
destroy:
(procedure) -> void
getattr:
(procedure path) -> (or (vector mode nlink uid gid size atime ctime mtime) #f)
init:
(procedure) -> void
link:
(procedure path path) -> value
mkdir:
(procedure path mode) -> value
mknod:
(procedure path mode) -> value
open:
(procedure path mode) -> (or handle #f)
readdir:
(procedure path) -> (or (list path ...) value)
readlink:
(procedure path) -> (or path #f)
read:
(procedure handle size offset) -> (or size string value)
release:
(procedure handle) -> value
rename:
(procedure path path) -> value
rmdir:
(procedure path) -> value
statfs:
(procedure path) -> (or (vector bsize blocks bfree bavail files ffree namemax) #f)
symlink:
(procedure path path) -> value
truncate:
(procedure path) -> value
unlink:
(procedure path) -> value
utimens:
(procedure path atime mtime) -> value
write:
(procedure handle string offset) -> (or size string value)

offset, size, mode, nlink, uid, gid, size, atime, ctime and mtime are numeric values with the obvious meanings. A path is a pathname string. bsize, blocks, bfree, bavail, files, ffree and namemax are positive numeric values corresponding to the statvfs(2) struct members of the those names.

A value may be any Scheme object and indicates whether the filesystem operation was successful. When #f, the filesystem will indicate a nonexistent file (ENOENT); any other value indicates success. Callbacks should signal other types of failure by raising an appropriate errno(3) value. For example, to signal insufficient permissions, an access: operation should (raise errno/perm).

A handle may be any Scheme object and represents a file handle. When returned as the result of an open: or create:callback, this value is provided to that file's subsequent read:, write: and release: operations. Note that this object is evicted until the corresponding file is closed, so it is more efficient (as well as memory-safe) to use simple values as file handles; the same caveats that apply to object-evict apply here. release: is guaranteed to be called once for every successful open:, while read: and write: should be prepared to be called multiple times with diverse offset values.

[procedure] (start-filesystem path filesystem) -> object

Mount filesystem at the given path.

path should be a pathname string indicating an empty directory.

On success, this procedure will block until the filesystem is unmounted, at which point it will return a non-false value. This may occur due to a signal, a call to stop-filesystem, or a user manually running fusermount -u path.

On failure, it will return #f immediately.

The effective exception handler for the filesystem's operations at path is that of start-filesystem's dynamic environment, and must always return with a suitable errno(3) integer value. Failure to do so may result in orphaned mounts, infinite loops, and locusts.

[procedure] (stop-filesystem path filesystem) -> void

Unmount filesystem from the given path.

path should be a pathname string and must exactly match the value provided to start-filesystem when the filesystem was mounted (according to string=?).

If the given filesystem isn't currently mounted at path, this procedure is a noop.

On other platforms, this procedure is a noop.

[constant] file/fifo
[constant] file/chr
[constant] file/blk
[constant] file/reg
[constant] file/dir
[constant] file/lnk
[constant] file/sock

These values correspond to the S_IF* flags specified by stat(2). They're not FUSE-specific, but may be useful when defining getattr: callbacks.

Author

Evan Hanson

Credit to Ivan Raikov for initial work on libfuse bindings and inspiration for the keyword-based API.

Credit to Jörg Wittenberger for lots of helpful bug hunting.

License

Copyright (c) 2013, 3-Clause BSD.