/[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

Annotation of /perl/trunk/Fuse.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 16 - (hide annotations)
Wed Jun 22 16:15:17 2005 UTC (17 years, 3 months ago) by dpavlin
File size: 12583 byte(s)
added changes from Mark Wilkinson to support mount options, list all
contributors in AUTHORS, added pod tests

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

  ViewVC Help
Powered by ViewVC 1.1.26