source: project/wiki/eggref/4/fuse

Last change on this file was 36801, checked in by evhan, 8 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 7.9 KB
Line 
1[[tags: egg]]
2
3== fuse
4
5[[toc:]]
6
7== Description
8
9A [[https://fuse.sourceforge.net/|FUSE]] interface.
10
11Installation requires the libfuse library and headers (API version 26)
12and a CHICKEN version 4.8.2 or newer.
13
14The source for this extension is available
15[[https://git.foldling.org/chicken-fuse.git|here]].
16
17'''This extension's interface is subject to change without notice or
18deprecation period.'''
19
20=== Requirements
21
22* [[concurrent-native-callbacks]]
23* [[foreigners]]
24* [[matchable]]
25
26=== Platform Notes
27
28'''This extension is only officially supported on Linux and OpenBSD.'''
29It has also been installed successfully on FreeBSD and Mac OS X, but
30tested far less thoroughly on those platforms.
31
32On OpenBSD, each filesystem's main loop is single-threaded and the
33'''{{{ioctl:}}}''' callback is not available.
34
35=== Runtime Structure
36
37Each filesystem is executed in a separate native thread that
38communicates with the (single, shared) CHICKEN runtime via Unix pipe,
39per [[/eggref/4/concurrent-native-callbacks|concurrent-native-callbacks]].
40Multiple filesystems can be run at once from within a single process,
41but FUSE operations are synchronous across all filesystems so
42long-running callbacks should be avoided.
43
44More importantly, care must be taken not to deadlock the Scheme runtime
45by requesting a filesystem operation from within CHICKEN that itself
46requires a response from CHICKEN, for example by accessing a file that's
47part of a running filesystem. The easiest way to avoid this situation is
48to run each filesystem in a more-or-less dedicated OS-level process
49whose sole responsibility is to service FUSE requests.
50
51== API
52
53<record>filesystem</record>
54<procedure>(filesystem? object) -> boolean</procedure>
55
56A {{filesystem}} is an opaque, {{defstruct}}-style record type
57representing a set of FUSE filesystem operations.
58
59<procedure>(make-filesystem #!key <operation> ...) -> filesystem</procedure>
60
61Create a FUSE filesystem.
62
63The keyword arguments to {{make-filesystem}} specify the resulting
64{{filesystem}}'s callback procedures. Each {{<operation>}} should be one
65the following:
66
67; {{access:}}:   {{(procedure path mode) -> value}}
68; {{chmod:}}:    {{(procedure path mode) -> value}}
69; {{chown:}}:    {{(procedure uid gid) -> value}}
70; {{create:}}:   {{(procedure path mode) -> (or handle false)}}
71; {{destroy:}}:  {{(procedure) -> void}}
72; {{flush:}}:    {{(procedure path) -> value}}
73; {{fsync:}}:    {{(procedure path) -> value}}
74; {{getattr:}}:  {{(procedure path) -> (or (vector mode nlink uid gid size atime ctime mtime) false)}}
75; {{init:}}:     {{(procedure) -> void}}
76; {{ioctl:}}:    {{(procedure path int pointer) -> value}}
77; {{link:}}:     {{(procedure path path) -> value}}
78; {{mkdir:}}:    {{(procedure path mode) -> value}}
79; {{mknod:}}:    {{(procedure path mode) -> value}}
80; {{open:}}:     {{(procedure path mode) -> (or handle false)}}
81; {{readdir:}}:  {{(procedure path) -> (or (list path ...) value)}}
82; {{readlink:}}: {{(procedure path) -> (or path false)}}
83; {{read:}}:     {{(procedure handle size offset) -> (or size string value)}}
84; {{release:}}:  {{(procedure handle) -> value}}
85; {{rename:}}:   {{(procedure path path) -> value}}
86; {{rmdir:}}:    {{(procedure path) -> value}}
87; {{statfs:}}:   {{(procedure path) -> (or (vector bsize blocks bfree bavail files ffree namemax) false)}}
88; {{symlink:}}:  {{(procedure path path) -> value}}
89; {{truncate:}}: {{(procedure path) -> value}}
90; {{unlink:}}:   {{(procedure path) -> value}}
91; {{utimens:}}:  {{(procedure path atime mtime) -> value}}
92; {{write:}}:    {{(procedure handle string offset) -> (or size string value)}}
93
94{{offset}}, {{size}}, {{mode}}, {{nlink}}, {{uid}}, {{gid}}, {{size}},
95{{atime}}, {{ctime}} and {{mtime}} are numeric values with the obvious
96meanings. A {{path}} is a pathname string. {{bsize}}, {{blocks}},
97{{bfree}}, {{bavail}}, {{files}}, {{ffree}} and {{namemax}} are positive
98numeric values corresponding to the {{statvfs(2)}} struct members of the
99same names.
100
101A {{value}} may be any Scheme object and indicates whether the
102filesystem operation was successful. When false, the filesystem will
103indicate a nonexistent file ({{ENOENT}}); any other value indicates
104success. Callbacks should signal other types of failures by raising an
105appropriate {{errno(3)}} value. For example, to signal insufficient
106permissions, an '''{{access:}}''' operation should {{(raise
107errno/perm)}}.
108
109A {{handle}} may be any Scheme object and represents a file handle. When
110returned as the result of an '''{{open:}}''' or
111'''{{create:}}'''callback, this value is provided to that file's
112subsequent '''{{read:}}''', '''{{write:}}''' and '''{{release:}}'''
113operations. '''{{release:}}''' is guaranteed to be called once for every
114successful '''{{open:}}''' or '''{{create:}}''', while '''{{read:}}'''
115and '''{{write:}}''' should be prepared to be called multiple times with
116diverse {{offset}} values.
117
118<procedure>(filesystem-start! path filesystem) -> (or false undefined)</procedure>
119
120Start {{filesystem}} at the given {{path}}.
121
122{{path}} should be a pathname string indicating an empty directory.
123
124On successful startup, the filesystem is mounted, its '''{{init:}}'''
125callback is executed, any threads waiting for the filesystem to start
126are unblocked, and a non-false value is returned. On failure, {{#f}} is
127returned immediately.
128
129{{filesystem-start!}} does not wait for filesystem initialization before
130returning. To block until the filesystem becomes available, use
131{{filesystem-wait!}}.
132
133The effective exception handler for the filesystem's operations at
134{{path}} is that of the call to {{filesystem-start!}}'s dynamic
135environment, and must ''always'' return with a suitable {{errno(3)}}
136integer value. Failure to do so may result in orphaned mounts, infinite
137loops, and locusts.
138
139<procedure>(filesystem-stop! path filesystem) -> undefined</procedure>
140
141Stop {{filesystem}} at the given {{path}}.
142
143{{path}} should be a pathname string and must exactly match the value
144provided to {{filesystem-start!}} when the {{filesystem}} was started
145(according to {{string=?}}).
146
147If the given {{filesystem}} isn't currently mounted at {{path}}, this
148procedure is a noop. Otherwise, the filesystem is unmounted, any threads
149waiting for the filesystem to stop are unblocked, and its
150'''{{destroy:}}''' callback is executed.
151
152{{filesystem-stop!}} does not wait for filesystem shutdown before
153returning. To block until the filesystem is fully stopped, use
154{{filesystem-wait!}}.
155
156<procedure>(filesystem-wait! path filesystem [status]) -> undefined</procedure>
157
158Block until {{filesystem}} is started or stopped at {{path}}.
159
160{{path}} should be a pathname string and must exactly match the value
161provided to {{filesystem-start!}} when the {{filesystem}} was started
162(according to {{string=?}}).
163
164The optional {{status}} argument should be a symbol indicating the
165filesystem state for which to wait, either {{started}} or {{stopped}}.
166If not specified, {{stopped}} is used.
167
168<procedure>(filesystem-running? path filesystem) -> boolean</procedure>
169
170Determine whether {{filesystem}} is currently running at {{path}}.
171
172{{path}} should be a pathname string and must exactly match the value
173provided to {{filesystem-start!}} when the {{filesystem}} was started
174(according to {{string=?}}).
175
176<constant>file/fifo</constant>
177<constant>file/chr</constant>
178<constant>file/blk</constant>
179<constant>file/reg</constant>
180<constant>file/dir</constant>
181<constant>file/lnk</constant>
182<constant>file/sock</constant>
183
184These values correspond to the {{S_IF*}} flags specified by {{stat(2)}}.
185They're not FUSE-specific, but may be useful when defining
186'''{{getattr:}}''' callbacks.
187
188== Examples
189
190Usage examples can be found in the project's
191[[https://git.foldling.org/chicken-fuse.git/src/examples/|examples]]
192directory.
193
194== Author
195
196[[/users/evan-hanson|Evan Hanson]]
197
198Credit to [[/users/ivan-raikov|Ivan Raikov]] for initial work on libfuse
199bindings and inspiration for the keyword-based API.
200
201Credit to [[/users/jorg-wittenberger|Jörg Wittenberger]] for lots of
202helpful bug hunting.
203
204== License
205
2063-Clause BSD
Note: See TracBrowser for help on using the repository browser.