source: project/wiki/eggref/5/fuse @ 36801

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

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

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