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

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

wiki: fuse doc update

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