source: project/wiki/eggref/4/fuse @ 30580

Last change on this file since 30580 was 30580, checked in by evhan, 7 years ago

wiki/fuse: doc update, fix create callback signature

File size: 5.9 KB
Line 
1[[tags: egg]]
2
3== fuse
4
5[[toc:]]
6
7=== Description
8
9A [[http://fuse.sourceforge.net/|FUSE]] interface.
10
11Installation requires the libfuse library and headers (API version 26)
12and CHICKEN 4.8.0 or newer.
13
14The source for this extension is available at
15[[https://bitbucket.org/evhan/chicken-fuse|Bitbucket]].
16
17==== Warning
18
19'''This extension is not yet stable.''' Its interface is subject to
20change, and I'd appreciate feedback and suggestions regarding the API.
21
22==== Platform Notes
23
24'''This extension is only officially supported on Linux.''' It has also
25been installed successfully on OpenBSD, FreeBSD and Mac OS X, but tested
26far less thoroughly on those platforms.
27
28On Linux, each filesystem operation is executed in its own green
29({{srfi-18}}) thread.
30
31On other platforms, filesystem operations are synchronous
32({{start-filesystem}} is single-threaded) and {{stop-filesystem}} is not
33supported.
34
35=== API
36
37<record>filesystem</record>
38<procedure>(filesystem? object) -> boolean</procedure>
39
40A {{filesystem}} is an opaque, {{defstruct}}-style record type
41representing a set of FUSE filesystem operations.
42
43<procedure>(make-filesystem #!key <operation> ...) -> filesystem</procedure>
44
45Create a FUSE filesystem.
46
47The keyword arguments to {{make-filesystem}} specify the resulting
48{{filesystem}}'s callback procedures. Each {{<operation>}} should be one
49the following:
50
51; {{access:}}:   {{(procedure path mode) -> value}}
52; {{chmod:}}:    {{(procedure path mode) -> value}}
53; {{chown:}}:    {{(procedure uid gid) -> value}}
54; {{create:}}:   {{(procedure path mode) -> (or handle #f)}}
55; {{destroy:}}:  {{(procedure) -> void}}
56; {{getattr:}}:  {{(procedure path) -> (or (vector mode nlink uid gid size atime ctime mtime) #f)}}
57; {{init:}}:     {{(procedure) -> void}}
58; {{link:}}:     {{(procedure path path) -> value}}
59; {{mkdir:}}:    {{(procedure path mode) -> value}}
60; {{mknod:}}:    {{(procedure path mode) -> value}}
61; {{open:}}:     {{(procedure path mode) -> (or handle #f)}}
62; {{readdir:}}:  {{(procedure path) -> (or (list path ...) value)}}
63; {{readlink:}}: {{(procedure path) -> (or path #f)}}
64; {{read:}}:     {{(procedure handle size offset) -> (or size string value)}}
65; {{release:}}:  {{(procedure handle) -> value}}
66; {{rename:}}:   {{(procedure path path) -> value}}
67; {{rmdir:}}:    {{(procedure path) -> value}}
68; {{statfs:}}:   {{(procedure path) -> (or (vector bsize blocks bfree bavail files ffree namemax) #f)}}
69; {{symlink:}}:  {{(procedure path path) -> value}}
70; {{truncate:}}: {{(procedure path) -> value}}
71; {{unlink:}}:   {{(procedure path) -> value}}
72; {{utimens:}}:  {{(procedure path atime mtime) -> value}}
73; {{write:}}:    {{(procedure handle string offset) -> (or size string value)}}
74
75{{offset}}, {{size}}, {{mode}}, {{nlink}}, {{uid}}, {{gid}}, {{size}},
76{{atime}}, {{ctime}} and {{mtime}} are numeric values with the obvious
77meanings. A {{path}} is a pathname string. {{bsize}}, {{blocks}},
78{{bfree}}, {{bavail}}, {{files}}, {{ffree}} and {{namemax}} are positive
79numeric values corresponding to the {{statvfs(2)}} struct members of the
80those names.
81
82A {{value}} may be any Scheme object and indicates whether the
83filesystem operation was successful. When {{#f}}, the filesystem will
84indicate a nonexistent file ({{ENOENT}}); any other value indicates
85success. Callbacks should signal other types of failure by raising an
86appropriate {{errno(3)}} value. For example, to signal insufficient
87permissions, an '''{{access:}}''' operation should {{(raise
88errno/perm)}}.
89
90A {{handle}} may be any Scheme object and represents a file handle. When
91returned as the result of an '''{{open:}}''' or
92'''{{create:}}'''callback, this value is provided to that file's
93subsequent '''{{read:}}''', '''{{write:}}''' and '''{{release:}}'''
94operations. Note that this object is evicted until the corresponding
95file is closed, so it is more efficient (as well as memory-safe) to use
96simple values as file handles; the same caveats that apply to
97{{object-evict}} apply here. '''{{release:}}''' is guaranteed to be
98called once for every successful '''{{open:}}''', while '''{{read:}}'''
99and '''{{write:}}''' should be prepared to be called multiple times with
100diverse {{offset}} values.
101
102<procedure>(start-filesystem path filesystem) -> object</procedure>
103
104Mount {{filesystem}} at the given {{path}}.
105
106{{path}} should be a pathname string indicating an empty directory.
107
108On success, this procedure will block until the filesystem is unmounted,
109at which point it will return a non-false value. This may occur due to a
110signal, a call to {{stop-filesystem}}, or a user manually running
111{{fusermount -u path}}.
112
113On failure, it will return {{#f}} immediately.
114
115The effective exception handler for the filesystem's operations at
116{{path}} is that of {{start-filesystem}}'s dynamic environment, and must
117''always'' return with a suitable {{errno(3)}} integer value. Failure to
118do so may result in orphaned mounts, infinite loops, and locusts.
119
120<procedure>(stop-filesystem path filesystem) -> void</procedure>
121
122Unmount {{filesystem}} from the given {{path}}.
123
124{{path}} should be a pathname string and must exactly match the value
125provided to {{start-filesystem}} when the {{filesystem}} was mounted
126(according to {{string=?}}).
127
128If the given {{filesystem}} isn't currently mounted at {{path}}, this
129procedure is a noop.
130
131On other platforms, this procedure is a noop.
132
133<constant>file/fifo</constant>
134<constant>file/chr</constant>
135<constant>file/blk</constant>
136<constant>file/reg</constant>
137<constant>file/dir</constant>
138<constant>file/lnk</constant>
139<constant>file/sock</constant>
140
141These values correspond to the {{S_IF*}} flags specified by {{stat(2)}}.
142They're not FUSE-specific, but may be useful when defining
143'''{{getattr:}}''' callbacks.
144
145=== Author
146
147[[/users/evan-hanson|Evan Hanson]]
148
149Credit to [[/users/ivan-raikov|Ivan Raikov]] for initial work on libfuse
150bindings and inspiration for the keyword-based API.
151
152Credit to [[/users/jorg-wittenberger|Jörg Wittenberger]] for lots of
153helpful bug hunting.
154
155=== License
156
157Copyright (c) 2013, 3-Clause BSD.
Note: See TracBrowser for help on using the repository browser.