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

Last change on this file since 30205 was 30205, checked in by evhan, 6 years ago

wiki: fuse doc update

File size: 5.2 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; {{symlink:}}:  {{(procedure path path) -> value}}
65; {{truncate:}}: {{(procedure path) -> value}}
66; {{unlink:}}:   {{(procedure path) -> value}}
67; {{utimens:}}:  {{(procedure path atime mtime) -> value}}
68; {{write:}}:    {{(procedure handle string offset) -> (or size string value)}}
69
70{{offset}}, {{size}}, {{mode}}, {{nlink}}, {{uid}}, {{gid}}, {{size}},
71{{atime}}, {{ctime}} and {{mtime}} are numeric values with the obvious
72meanings. A {{path}} is a pathname string.
73
74A {{value}} may be any Scheme object and indicates whether the
75filesystem operation was successful. When {{#f}}, the filesystem will
76indicate a nonexistent file ({{ENOENT}}); any other value indicates
77success. Callbacks should signal other types of failure by raising an
78appropriate {{errno(3)}} value. For example, to signal insufficient
79permissions, an '''{{access:}}''' operation should {{(raise
80errno/perm)}}.
81
82A {{handle}} may be any Scheme object and represents a file handle. When
83returned as the result of an '''{{open:}}''' callback, this value is
84provided to that file's subsequent '''{{read:}}''', '''{{write:}}''' and
85'''{{release:}}''' operations. Note that this object is evicted until
86the corresponding file is closed, so it is more efficient (as well as
87memory-safe) to use simple values as file handles; the same caveats
88that apply to {{object-evict}} apply here. '''{{release:}}''' is
89guaranteed to be called once for every successful '''{{open:}}''', while
90'''{{read:}}''' and '''{{write:}}''' should be prepared to be called
91multiple times with diverse {{offset}} values.
92
93<procedure>(start-filesystem path filesystem) -> object</procedure>
94
95Mount {{filesystem}} at the given {{path}}.
96
97{{path}} should be a pathname string indicating an empty directory.
98
99On success, this procedure will block until the filesystem is unmounted,
100at which point it will return a non-false value. This may occur due to a
101signal, a call to {{stop-filesystem}}, or a user manually running
102{{fusermount -u path}}.
103
104On failure, it will return {{#f}} immediately.
105
106The effective exception handler for the filesystem's operations at
107{{path}} is that of {{start-filesystem}}'s dynamic environment, and must
108''always'' return with a suitable {{errno(3)}} integer value. Failure to
109do so may result in orphaned mounts, infinite loops, and locusts.
110
111<procedure>(stop-filesystem path filesystem) -> void</procedure>
112
113Unmount {{filesystem}} from the given {{path}}.
114
115{{path}} should be a pathname string and must exactly match the value
116provided to {{start-filesystem}} when the {{filesystem}} was mounted
117(according to {{string=?}}).
118
119If the given {{filesystem}} isn't currently mounted at {{path}}, this
120procedure is a noop.
121
122On OpenBSD, this procedure is a noop.
123
124<constant>file/fifo</constant>
125<constant>file/chr</constant>
126<constant>file/blk</constant>
127<constant>file/reg</constant>
128<constant>file/dir</constant>
129<constant>file/lnk</constant>
130<constant>file/sock</constant>
131
132These values correspond to the {{S_IF*}} flags specified by {{stat(2)}}.
133They're not FUSE-specific, but may be useful when defining
134'''{{getattr:}}''' callbacks.
135
136=== Author
137
138[[/users/evan-hanson|Evan Hanson]]
139
140=== License
141
142Copyright (c) 2013, 3-Clause BSD.
Note: See TracBrowser for help on using the repository browser.