/[fuse.before_github]/perl/trunk/Fuse.pm
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /perl/trunk/Fuse.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 14 - (show annotations)
Sun Apr 10 13:30:11 2005 UTC (17 years, 5 months ago) by richdawe
File size: 11902 byte(s)
Add support for operations supported by FUSE 2.2.1 (flush, release, fsync, extended attributes); bump version to 0.06.

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

  ViewVC Help
Powered by ViewVC 1.1.26