[[tags: egg]]

== fuse

[[toc:]]

=== Description

A [[http://fuse.sourceforge.net/|FUSE]] interface.

Installation requires a libfuse library and headers with API version 26
and CHICKEN 4.8.0 or newer.

The source for this extension is available at
[[https://bitbucket.org/evhan/chicken-fuse|BitBucket]].

==== Warning

'''This extension is not yet stable!''' It has only been lightly tested
and its interface is subject to change. I'd appreciate feedback and
suggestions regarding its API.

=== API

<record>filesystem</record>
<procedure>(filesystem? object) -> boolean</procedure>

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

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

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) -> value}}
; {{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}}
; {{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.

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:}}''' 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</procedure>

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</procedure>

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.

<constant>file/fifo</constant>
<constant>file/chr</constant>
<constant>file/blk</constant>
<constant>file/reg</constant>
<constant>file/dir</constant>
<constant>file/lnk</constant>
<constant>file/sock</constant>

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

[[/users/evan-hanson|Evan Hanson]]

=== License

Copyright (c) 2013, 3-Clause BSD.