1 |
package Fuse; |
2 |
|
3 |
use 5.006; |
4 |
use strict; |
5 |
use warnings; |
6 |
use Errno; |
7 |
use Carp; |
8 |
|
9 |
require Exporter; |
10 |
require DynaLoader; |
11 |
use AutoLoader; |
12 |
use Data::Dumper; |
13 |
our @ISA = qw(Exporter DynaLoader); |
14 |
|
15 |
# Items to export into callers namespace by default. Note: do not export |
16 |
# names by default without a very good reason. Use EXPORT_OK instead. |
17 |
# Do not simply export all your public functions/methods/constants. |
18 |
|
19 |
# This allows declaration use Fuse ':all'; |
20 |
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK |
21 |
# will save memory. |
22 |
our %EXPORT_TAGS = ( 'all' => [ qw( |
23 |
FUSE_DEBUG |
24 |
) ] ); |
25 |
|
26 |
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); |
27 |
|
28 |
our @EXPORT = qw( |
29 |
FUSE_DEBUG |
30 |
); |
31 |
our $VERSION = '0.04'; |
32 |
|
33 |
sub AUTOLOAD { |
34 |
# This AUTOLOAD is used to 'autoload' constants from the constant() |
35 |
# XS function. If a constant is not found then control is passed |
36 |
# to the AUTOLOAD in AutoLoader. |
37 |
|
38 |
my $constname; |
39 |
our $AUTOLOAD; |
40 |
($constname = $AUTOLOAD) =~ s/.*:://; |
41 |
croak "& not defined" if $constname eq 'constant'; |
42 |
my $val = constant($constname, @_ ? $_[0] : 0); |
43 |
if ($! != 0) { |
44 |
if ($!{EINVAL}) { |
45 |
$AutoLoader::AUTOLOAD = $AUTOLOAD; |
46 |
goto &AutoLoader::AUTOLOAD; |
47 |
} |
48 |
else { |
49 |
croak "Your vendor has not defined Fuse macro $constname"; |
50 |
} |
51 |
} |
52 |
{ |
53 |
no strict 'refs'; |
54 |
# Fixed between 5.005_53 and 5.005_61 |
55 |
if ($] >= 5.00561) { |
56 |
*$AUTOLOAD = sub () { $val }; |
57 |
} |
58 |
else { |
59 |
*$AUTOLOAD = sub { $val }; |
60 |
} |
61 |
} |
62 |
goto &$AUTOLOAD; |
63 |
} |
64 |
|
65 |
bootstrap Fuse $VERSION; |
66 |
|
67 |
sub main { |
68 |
my (@subs) = (0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0); |
69 |
my (@names) = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink |
70 |
rename link chmod chown truncate utime open read write statfs); |
71 |
my ($tmp) = 0; |
72 |
my (%mapping) = map { $_ => $tmp++ } (@names); |
73 |
my (%otherargs) = (debug=>0, mountpoint=>""); |
74 |
while(my $name = shift) { |
75 |
my ($subref) = shift; |
76 |
if(exists($otherargs{$name})) { |
77 |
$otherargs{$name} = $subref; |
78 |
} else { |
79 |
croak "There is no function $name" unless exists($mapping{$name}); |
80 |
croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless $subref; |
81 |
croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref); |
82 |
croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref) eq "CODE"; |
83 |
$subs[$mapping{$name}] = $subref; |
84 |
} |
85 |
} |
86 |
perl_fuse_main($otherargs{debug},$otherargs{mountpoint},@subs); |
87 |
} |
88 |
|
89 |
# Autoload methods go after =cut, and are processed by the autosplit program. |
90 |
|
91 |
1; |
92 |
__END__ |
93 |
|
94 |
=head1 NAME |
95 |
|
96 |
Fuse - write filesystems in Perl using FUSE |
97 |
|
98 |
=head1 SYNOPSIS |
99 |
|
100 |
use Fuse; |
101 |
my ($mountpoint) = ""; |
102 |
$mountpoint = shift(@ARGV) if @ARGV; |
103 |
Fuse::main(mountpoint=>$mountpoint, getattr=>\&my_getattr, getdir=>\&my_getdir, ...); |
104 |
|
105 |
=head1 DESCRIPTION |
106 |
|
107 |
This lets you implement filesystems in perl, through the FUSE |
108 |
(Filesystem in USErspace) kernel/lib interface. |
109 |
|
110 |
FUSE expects you to implement callbacks for the various functions. |
111 |
|
112 |
NOTE: I have only tested the things implemented in example.pl! |
113 |
It should work, but some things may not. |
114 |
|
115 |
In the following definitions, "errno" can be 0 (for a success), |
116 |
-EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really. |
117 |
|
118 |
You can import standard error constants by saying something like |
119 |
"use POSIX qw(EDOTDOT ENOANO);". |
120 |
|
121 |
Every constant you need (file types, open() flags, error values, |
122 |
etc) can be imported either from POSIX or from Fcntl, often both. |
123 |
See their respective documentations, for more information. |
124 |
|
125 |
=head2 EXPORT |
126 |
|
127 |
None by default. |
128 |
|
129 |
=head2 EXPORTABLE CONSTANTS |
130 |
|
131 |
None. |
132 |
|
133 |
=head2 FUNCTIONS |
134 |
|
135 |
=head3 Fuse::main |
136 |
|
137 |
Takes arguments in the form of hash key=>value pairs. There are |
138 |
many valid keys. Most of them correspond with names of callback |
139 |
functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'. |
140 |
A few special keys also exist: |
141 |
|
142 |
|
143 |
debug => boolean |
144 |
|
145 |
=over 1 |
146 |
|
147 |
This turns FUSE call tracing on and off. Default is 0 (which means off). |
148 |
|
149 |
=back |
150 |
|
151 |
mountpoint => string |
152 |
|
153 |
=over 1 |
154 |
|
155 |
The point at which to mount this filesystem. There is no default, you must |
156 |
specify this. An example would be '/mnt'. |
157 |
|
158 |
=back |
159 |
|
160 |
unthreaded => boolean |
161 |
|
162 |
=over 1 |
163 |
|
164 |
This turns FUSE multithreading off and on. NOTE: This perlmodule does not |
165 |
currently work properly in multithreaded mode! The author is unfortunately |
166 |
not familiar enough with perl-threads internals, and according to the |
167 |
documentation available at time of writing (2002-03-08), those internals are |
168 |
subject to changing anyway. Note that singlethreaded mode also means that |
169 |
you will not have to worry about reentrancy, though you will have to worry |
170 |
about recursive lookups (since the kernel holds a global lock on your |
171 |
filesystem and blocks waiting for one callback to complete before calling |
172 |
another). |
173 |
|
174 |
I hope to add full multithreading functionality later, but for now, I |
175 |
recommend you leave this option at the default, 1 (which means |
176 |
unthreaded, no threads will be used and no reentrancy is needed). |
177 |
|
178 |
=back |
179 |
|
180 |
=head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT |
181 |
|
182 |
=head3 getattr |
183 |
|
184 |
Arguments: filename. |
185 |
Returns a list, very similar to the 'stat' function (see |
186 |
perlfunc). On error, simply return a single numeric scalar |
187 |
value (e.g. "return -ENOENT();"). |
188 |
|
189 |
FIXME: the "ino" field is currently ignored. I tried setting it to 0 |
190 |
in an example script, which consistently caused segfaults. |
191 |
|
192 |
Fields (the following was stolen from perlfunc(1) with apologies): |
193 |
|
194 |
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, |
195 |
$atime,$mtime,$ctime,$blksize,$blocks) |
196 |
= getattr($filename); |
197 |
|
198 |
Here are the meaning of the fields: |
199 |
|
200 |
0 dev device number of filesystem |
201 |
1 ino inode number |
202 |
2 mode file mode (type and permissions) |
203 |
3 nlink number of (hard) links to the file |
204 |
4 uid numeric user ID of file's owner |
205 |
5 gid numeric group ID of file's owner |
206 |
6 rdev the device identifier (special files only) |
207 |
7 size total size of file, in bytes |
208 |
8 atime last access time in seconds since the epoch |
209 |
9 mtime last modify time in seconds since the epoch |
210 |
10 ctime inode change time (NOT creation time!) in seconds |
211 |
since the epoch |
212 |
11 blksize preferred block size for file system I/O |
213 |
12 blocks actual number of blocks allocated |
214 |
|
215 |
(The epoch was at 00:00 January 1, 1970 GMT.) |
216 |
|
217 |
=head3 readlink |
218 |
|
219 |
Arguments: link pathname. |
220 |
Returns a scalar: either a numeric constant, or a text string. |
221 |
|
222 |
This is called when dereferencing symbolic links, to learn the target. |
223 |
|
224 |
example rv: return "/proc/self/fd/stdin"; |
225 |
|
226 |
=head3 getdir |
227 |
|
228 |
Arguments: Containing directory name. |
229 |
Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0). |
230 |
|
231 |
This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call. |
232 |
|
233 |
example rv: return ('.', 'a', 'b', 0); |
234 |
|
235 |
=head3 mknod |
236 |
|
237 |
Arguments: Filename, numeric modes, numeric device |
238 |
Returns an errno (0 upon success, as usual). |
239 |
|
240 |
This function is called for all non-directory, non-symlink nodes, |
241 |
not just devices. |
242 |
|
243 |
=head3 mkdir |
244 |
|
245 |
Arguments: New directory pathname, numeric modes. |
246 |
Returns an errno. |
247 |
|
248 |
Called to create a directory. |
249 |
|
250 |
=head3 unlink |
251 |
|
252 |
Arguments: Filename. |
253 |
Returns an errno. |
254 |
|
255 |
Called to remove a file, device, or symlink. |
256 |
|
257 |
=head3 rmdir |
258 |
|
259 |
Arguments: Pathname. |
260 |
Returns an errno. |
261 |
|
262 |
Called to remove a directory. |
263 |
|
264 |
=head3 symlink |
265 |
|
266 |
Arguments: Existing filename, symlink name. |
267 |
Returns an errno. |
268 |
|
269 |
Called to create a symbolic link. |
270 |
|
271 |
=head3 rename |
272 |
|
273 |
Arguments: old filename, new filename. |
274 |
Returns an errno. |
275 |
|
276 |
Called to rename a file, and/or move a file from one directory to another. |
277 |
|
278 |
=head3 link |
279 |
|
280 |
Arguments: Existing filename, hardlink name. |
281 |
Returns an errno. |
282 |
|
283 |
Called to create hard links. |
284 |
|
285 |
=head3 chmod |
286 |
|
287 |
Arguments: Pathname, numeric modes. |
288 |
Returns an errno. |
289 |
|
290 |
Called to change permissions on a file/directory/device/symlink. |
291 |
|
292 |
=head3 chown |
293 |
|
294 |
Arguments: Pathname, numeric uid, numeric gid. |
295 |
Returns an errno. |
296 |
|
297 |
Called to change ownership of a file/directory/device/symlink. |
298 |
|
299 |
=head3 truncate |
300 |
|
301 |
Arguments: Pathname, numeric offset. |
302 |
Returns an errno. |
303 |
|
304 |
Called to truncate a file, at the given offset. |
305 |
|
306 |
=head3 utime |
307 |
|
308 |
Arguments: Pathname, numeric actime, numeric modtime. |
309 |
Returns an errno. |
310 |
|
311 |
Called to change access/modification times for a file/directory/device/symlink. |
312 |
|
313 |
=head3 open |
314 |
|
315 |
Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY |
316 |
and O_SYNC, constants you can import from POSIX). |
317 |
Returns an errno. |
318 |
|
319 |
No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open(). |
320 |
Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success. |
321 |
|
322 |
=head3 read |
323 |
|
324 |
Arguments: Pathname, numeric requestedsize, numeric offset. |
325 |
Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data. |
326 |
|
327 |
Called in an attempt to fetch a portion of the file. |
328 |
|
329 |
=head3 write |
330 |
|
331 |
Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to |
332 |
find the buffersize. |
333 |
Returns an errno. |
334 |
|
335 |
Called in an attempt to write (or overwrite) a portion of the file. Be prepared because $buffer could contain random binary data with NULLs and all sorts of other wonderful stuff. |
336 |
|
337 |
=head3 statfs |
338 |
|
339 |
Arguments: none |
340 |
Returns any of the following: |
341 |
|
342 |
-ENOANO() |
343 |
|
344 |
or |
345 |
|
346 |
$namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize |
347 |
|
348 |
or |
349 |
|
350 |
-ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize |
351 |
|
352 |
=head1 AUTHOR |
353 |
|
354 |
Mark Glines, E<lt>mark@glines.orgE<gt> |
355 |
|
356 |
=head1 SEE ALSO |
357 |
|
358 |
L<perl>, the FUSE documentation. |
359 |
|
360 |
=cut |